atlocale

atlocale is a tool that allows you to translate a locale folder containing multiple JSON files or a CSV file into into multiple languages using Google Translate, DeepL (free/pro), Azure Translator, Amazon Translate, or manually. Do you want yur product or services to be translated into multiple languages using automated translation-services of your choice? Then atlocale is for you.

atlocale supports different types of interpolation, such as (ICU: {name}, i18next: {{name}}, sprintf: %s). Interpolation are replaced by placeholders (e.g. <0 />) before being passed to the translation service, so their structure doesn't get mangled by the translation.

Installation

$ yarn add atlocale
# or
$ npm i -S atlocale

Running atlocale

$ yarn atlocale
# or
$ npx atlocale

Getting Started

Running yarn atlocale will automatically create a .atlocale folder with a config.json file at your project root directory if it doesn't exist. You can edit the config.json file to change the default configuration. You can override the default configuration by paasing the config file as an argument to yarn atlocale. eg.

$ yarn atlocale -i locales -d -c service-account.json

$ yarn atlocale -i locales -s manual

Directory Structure

You can specify your locales/i18n directory structure using the --directory-structure option.

Default

locales
├── de
├── en
│   ├── login.json
│   └── register.json
├── fr
└── it

If you don't specify another source language, this tool will translate all files located in the en into all other languages that exist as directories. A single language directory (e.g. en) should only contain JSON files. Sub-directories and other files will be ignored.

Ngx-translate

i18n
├── de.json
├── en.json
├── fr.json
└── it.json

If you don't specify another source language, this tool will translate en.json into all other languages that exist as files. The i18n directory should only contain JSON files. Sub-directories and other files will be ignored.

File Structure

There are two ways that atlocale can interpret files:

Natural Language (natural)
Key-Based (key-based)

If you don't specify a file structure type, atlocale will automatically determine the type on a per-file basis. In most cases, this is sufficient.

Natural Language

This is the default way that this tool will interpret your source files. The keys will be used as the basis of translations. If one or more of the values in your source files don't match their respective key, you'll see a warning as this could indicate an inconsistency in your translations. You can fix those inconsistencies by passing the --fix-inconsistencies flag.

{
  "Your username doesn't exist.": "Your username doesn't exist.",
  "{email} is not a valid email address.": "{email} is not a valid email address."
}

Key-Based

If you pass use the keybased option (--type keybased), this tool will use the source file's values as the basis of translations. Keys can be nested, the structure will be transferred over to the translated files as well.

{
  "ERRORS": {
    "USERNAME": "Your username doesn't exist.",
    "EMAIL": "{email} is not a valid email address."
  },
  "LOGIN": "Login",
  "FORGOT_PASSWORD": "Forgot password?"
}

CSV File

atlocale can read CSV files (e.g. for Google Docs or Microsoft Excel).

There're two required configuration options for CSV files: fileFormat and fileSrc.

{ 
  "fileFormat": "csv",
  "fileSrc": "./directory/to/csv/file.csv"
}

Available Services

As of this release, atlocale offers five services:

google-translate (default, uses Google Translate to translate strings)
deepl (uses DeepL Pro to translate strings)
deepl-free (uses DeepL Free to translate strings)
azure (uses Azure's Translator Text to translate strings)
amazon-translate (uses Amazon Translate to translate strings)
manual (allows you to translate strings manually by entering them into the CLI)
dry-run (outputs a list of strings that will be translated without touching any files)

You can select a service using the -s or --service option. If you specify the --list-services flag, atlocale will output a list of all available services.

Google Translate

To use this tool with Google Translate, you need to obtain valid credentials from Google. Follow these steps to get them:

Select or create a Cloud Platform project
Enable billing for your project (optional, I think)
Enable the Google Cloud Translation API
Set up authentication with a service account so you can access the API from your local workstation

You can specify the location of your downloaded JSON key file using the -c or --config option.

DeepL

To use this tool with DeepL, you need to obtain an API key from their website. If you don't have a Developer account yet, you can create one here.

DeepL Pro charges a fixed monthly price plus a variable fee for every 500 translated characters.

DeepL Free is limited to 500,000 characters translated per month.

After you have completed your sign-up, you can pass the API key to atlocale using the -c or --config option.

You can also provide a formality by adding it to the config string after the API key, separated by a comma: --config apiKey,formality. This feature currently only works for target languages "DE" (German), "FR" (French), "IT" (Italian), "ES" (Spanish), "NL" (Dutch), "PL" (Polish), "PT-PT", "PT-BR" (Portuguese) and "RU" (Russian).Possible options are:

"default" (default) "more" - for a more formal language "less" - for a more informal language

^Reference

Azure Translator Text

To use this tool with Azure's Translator Text, you need to obtain an API key from their website. Sign Up for an Azure account if you don't have one already and create a new translator instance. You'll get an API key soon after that which you can pass to atlocale using the -c or --config flag.

You can also provide a region by adding it to the config string after the API key, separated by a comma: --config apiKey,region. As of this version, the following regions are available:

australiaeast, brazilsouth, canadacentral, centralindia, centralus, centraluseuap, eastasia, eastus, eastus2, francecentral, japaneast, japanwest, koreacentral, northcentralus, northeurope, southcentralus, southeastasia, uksouth, westcentralus, westeurope, westus, westus2, and southafricanorth

^Reference

As of now, the first 2M characters of translation per month are free. After that you'll have to pay $10 per 1M characters that you translate.

Amazon Translate

Create an AWS account
Create an IAM user with the permissions required for Amazon Translate. A policy file like the following should work:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "comprehend:DetectDominantLanguage",
                "translate:TranslateText"
            ],
            "Resource": "*"
        }
    ]
}

Configure your AWS user credentials locally, or wherever you will be running atlocale. There are many ways to do this, but it is best to use something like shared credentials. Hard coded credentials should not be used for anything beyond proof of concept.
Create a json configuration file that defines the AWS region you want to use Translate in.

You can provide a path to the json configuration file via the --config flag. You may define any properties from TranslateClientConfig and they will be passed as the first argument to the Translate Constructor. At a minimum, this must include the AWS region.

Amazon Translate offers a free tier, but is paid after that. See their pricing page for details.

Manual

This service doesn't require any configuration. You will be prompted to translate the source strings manually in the console.

Available Matchers

Matchers are used to replace interpolations with placeholders before they are sent to the translation service. This ensures that interpolations don't get scrambled in the process. As of this release, atlocale offers four matchers for different styles of interpolation:

icu (default, matches [ICU MessageFormat]
i18next (matches i18next interpolations)
sprintf (matches sprintf-style interpolations like %s)
none (doesn't match any interpolations)

You can select a matchers using the -m or --matcher option. If you specify the --list-matchers flag, atlocale will output a list of all available matchers.

Available Options

Options:
  -i, --input <inputDir>                        the directory containing language directories (default: ".")
  -l, --source-language <sourceLang>            specify the source language (default: "en")
  -t, --type <key-based|natural|auto>           specify the file structure type (default: "auto")
  -s, --service <service>                       selects the service to be used for translation (default: "google-translate")
  --list-services                               outputs a list of available services
  -m, --matcher <matcher>                       selects the matcher to be used for interpolations (default: "icu")
  --list-matchers                               outputs a list of available matchers
  -c, --config <value>                          supply a config parameter (e.g. path to key file) to the translation service
  -f, --fix-inconsistencies                     automatically fixes inconsistent key-value pairs by setting the value to the key
  -d, --delete-unused-strings                   deletes strings in translation files that don't exist in the template
  -h, --help                                    output usage information
  --directory-structure <default|ngx-translate> the locale directory structure (default: "default")
  --decode-escapes                              decodes escaped HTML entities like &#39; into normal UTF-8 characters

Contributing

If you'd like to contribute to this project, please feel free to open a pull request.

Ezehuche/atlocale