npm package: @lcbase/i18n-vendor
Description: i18n translation vendor cli tool
Author: @lcbase
Latest version: 0.10.0

# i18n translation vendor cli tool

## Pipeline

> **Note**: This section is taken from [formatjs - Application Workflow](https://formatjs.io/docs/getting-started/application-workflow)

![i18n translation pipeline](https://formatjs.io/assets/images/workflow-cfcf0fe32b9a2d1097fcf2f11ed8b384.svg)

#### 1. **Extraction**: This step aggregates all `message`s from your application into a single JSON file along with `description`, ready to be translated.

#### 2. **Upload Messages**: This step uploads the JSON file to your translation vendor.

#### 3. **Download Translations**: This step either polls your translation vendor or hook into your vendor to download translated messages in the set of locales that you configured.

#### 4. **Commit**: This commits back translation messages to the codebase.

> **Note**: This tool only supports step 2 and 3.

## Required

### System

- **Nodejs version**: >=16

### Authentication

Create a service account that connect as a bot user that belongs to your app.

#### 1. Go to the [Google Developers Console](https://console.developers.google.com/)

#### 2. Select your project or create a new one (and then select it)

#### 3. Enable the `Sheets API` for your project

- `Menu sidebar` -> `APIs & services`
- Click the blue `Enable APIs and Services` button in the top bar
- Search for `sheets`
- Click on `Google Sheets API`
- Click the blue `Enable` button

#### 4. Enable the `Google Drive API` for your project

- `Menu sidebar` -> `APIs & services`
- Click the blue `Enable APIs and Services` button in the top bar
- Search for `Google Drive API`
- Click on `Google Sheets API`
- Click the blue `Enable` button

#### 5. Create a service account for your project

- `Menu sidebar` -> `APIs & services` -> `Credentials`
- Click blue `+ CREATE CREDENTIALS` button in the top bar and select `Service account` option
- Enter `name`, `description`
- You can skip step 2 `Grant this service account access to project` and step 3 `Grant users access to this service account`
- Click `DONE` button
- Select the created service account
- Select the `KEYS` tab in the top bar
- Select `ADD KEY` dropdown
- Select `Create new key` option
- Select the Key type `json`
- Click `CREATE` button
- Download the `credentials` file and save it in your computer.

> **Note:** Be careful - never check your API keys / secrets into version control (git)

## Installation

- pnpm

````sh
pnpm add -D @lcbase/i18n-vendor

## CLI

Add the following command to your package.json scripts:

```json
{
  "scripts": {
    "upload": "i18n-vendor upload [options] <files...>",
    "download": "i18n-vendor download [options]",
    "delete": "i18n-vendor delete [options]"
  }
}
````

### Required option `-c, --creds <path>`

To run the commands you need to provide a `credentials` file using the `-c, --creds <path>` option.

### Upload

```sh
pnpm upload --help

# Usage: i18n-vendor upload [options] <files...>

# Upload the JSON language file to translation vendor

# Options:
#  -c, --creds <path>                Google authentication credentials json file
#  -ssid, --spreadsheet-id <string>  Google sheet pubished ID
#  -t, --tab <number>                Google sheet tab index (default: "0")
#  -p, --project-name <string>       Project name
#  -l, --default-locale <string>     Default locale is 'en'
#  -h, --help                        display help for command
```

### Download

```sh
pnpm download --help

# Usage: i18n-vendor download [options]

# Download the JSON language file from  translation vendor

# Options:
#  -c, --creds <path>                Google authentication credentials json file
#  -ssid, --spreadsheet-id <string>  Google sheet pubished ID
#  -t, --tab <number>                Google sheet tab index (default: "0")
#  -o, --output-folder <path>        output file and folder location
#  -p, --project-name <string>       Project name
#  -h, --help                        display help for command
```

### Delete

```sh
pnpm delete --help

# Usage: i18n-vendor delete [options]

# Delete the spreadsheet by file id

# Options:
#  -c, --creds <path>           Google authentication credentials json file
#  -p, --project-name <string>  Project name
#  -a, --all <boolean>          Delete all files (default: true)
#  -h, --help                   display help for command
```

## i18n format

- The filename should be a languageCode ["-" scriptCode] ["-" regionCode ] \*("-" variant ) subsequence of the [unicode_language_id](https://unicode.org/reports/tr35/#Unicode_language_identifier) grammar. languageCode is either a two-letter ISO 639-1 language code or a three-letter ISO 639-2 language code.

  E.g: `en.json`, `fr.json`, `vi.json`, `ko.json`

- The File structure:

```json
{
  "key": {
    "message": "message",
    "description": "description"
  }
}
```

- Sample file

```json
{
  "title": {
    "message": "title",
    "description": "App Title"
  },
  "homeTitle": {
    "message": "Home Page",
    "description": "Home Page title"
  },
  "aboutTitle": {
    "message": "About Page",
    "description": "About Page Title"
  }
}
```

## Note and Tips

### Note

- This tool uses `google spreadsheet` to make i18n translation vendor using [googleapis](https://www.npmjs.com/package/googleapis) npm packages.

### Tips

#### 1. Put your the `credentials` file to `.gitignore` file.

#### 2. Create a new spreadsheet manually on your google account and share it to the `service account's email` with the access permission as `editor`.

- This makes it easy to manage the spreadsheet using the UI.
- You can fully control it with `owner` access permission.

#### 3. Credentials file can be used for many different projects in your company

#### 4. Should delete the file after the project is finished to free up drive memory of the bot service account