i18n translation vendor cli tool

Pipeline

Note: This section is taken from formatjs - Application Workflow

1. Extraction: This step aggregates all messages 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

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

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

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

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

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 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:

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

• Sample file

{
  "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 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