json-autotranslate

This tool allows you to translate a locale folder containing multiple JSON files
into multiple languages using Google Translate, DeepL (free/pro), Azure
Translator, Amazon Translate, or manually. You can either use the translation
keys (natural translation) or their values (key-based translation) as a source
for translations.

If some of the strings have already been translated, they won't be translated
again. This improves performance and ensures that you won't accidentally lose
existing translations.

Interpolations (ICU: {name}, i18next: {{name}}, sprintf: %s) 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

``shell $ yarn add json-autotranslate

`or`


$ npm i -S json-autotranslate


Running json-autotranslate

`shell $ yarn json-autotranslate

`or`


$ npx json-autotranslate

$3

Translate natural language source files located in the localesdirectory using Google Translate and delete existing keys in translated JSON files that are no longer used.

`shell $ yarn json-autotranslate -i locales -d -c service-account.json`

Manually translate key-based source files located in the locales directory.

`shell $ yarn json-autotranslate -i locales -s manual`

`Directory Structure`

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

`$3`

`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 theeninto 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.

`$3`

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

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

`File Structure`

There are two ways that json-autotranslate can interpret files:

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

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

`$3`

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.

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

`$3`

If you pass use the key-based option (--type key-based), 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.

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

`Available Services`

As of this release, json-autotranslate 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) - OpenAI (uses gpt-4o and can take a context file path from the context option) - 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 --serviceoption. If you specify the--list-servicesflag, json-autotranslate will output a list of all available services.

`$3`

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

1. [Select or create a Cloud Platform project][projects] 2. [Enable billing for your project][billing] (optional, I think) 3. [Enable the Google Cloud Translation API][enable_api] 4. [Set up authentication with a service account][auth] so you can access the API from your local workstation

[projects]: https://console.cloud.google.com/project [billing]: https://support.google.com/cloud/answer/6293499#enable-billing [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=translate.googleapis.com [auth]: https://cloud.google.com/docs/authentication/getting-started

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

`$3`

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 json-autotranslate using the-c or --config option.

The value of the --configargument is a comma separated string with the following:appKey,formality,batchSize.

The formalityargument 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

To improve performance and prevent DeepL rate-limiting json-autotranslate batches multiple tokens into a single translation request. By default, thebatchSize is set to 1000, meaning that 1000tokens are translated at once. This can be controlled by adjusting the value in the--configparameter. This value was chosen because the DeepL prevents the body of a request to be larger than128 KiB (128 · 1024 bytes)`. Based on experimentation, even with long tokens, this limit is not reached.

^Reference

`$3`

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 json-autotranslate using the-c or --config flag.

Unless you configure a global translator instance you will need to 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. See their pricing

`$3`

- 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 json-autotranslate. 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 --configflag. 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.

`$3`

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, json-autotranslate offers four matchers for different styles of interpolation:

- icu (default, matches ICU MessageFormat interpolations) - 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 --matcheroption. If you specify the--list-matchersflag, json-autotranslate will output a list of all available matchers.

`Available Options`

`Options: -i, --input the directory containing language directories (default: ".") --exclude exclude files matching the given glob pattern --cache set the cache directory (default: ".json-autotranslate-cache") -l, --source-language specify the source language (default: "en") -t, --type specify the file structure type (default: "auto") -a, --with-arrays enables support for arrays in files, but removes support for keys named 0, 1, 2, etc. -s, --service selects the service to be used for translation (default: "google-translate") -g, --glossaries [glossariesDir] set the glossaries folder to be used by DeepL. Keep empty for automatic determination of matching glossary -a, --appName specify the name of your app to distinguish DeepL glossaries (if sharing an API key between multiple projects) (default: "json-autotranslate") --context set the context that is used by DeepL for translations, for OpenAI it is the path to the json file containing the context for each key --list-services outputs a list of available services -m, --matcher selects the matcher to be used for interpolations (default: "icu") --list-matchers outputs a list of available matchers -c, --config 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 --directory-structure the locale directory structure --decode-escapes decodes escaped HTML entities like ' into normal UTF-8 characters -o, --overwrite overwrite already present translations -h, --help display help for command``

Contributing

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

json-autotranslate

If some of the strings have already been translated, they won't be translated
again. This improves performance and ensures that you won't accidentally lose
existing translations.

Installation

``shell $ yarn add json-autotranslate

`or`


$ npm i -S json-autotranslate


Running json-autotranslate

`shell $ yarn json-autotranslate

`or`


$ npx json-autotranslate

$3

Translate natural language source files located in the localesdirectory using Google Translate and delete existing keys in translated JSON files that are no longer used.

`shell $ yarn json-autotranslate -i locales -d -c service-account.json`

Manually translate key-based source files located in the locales directory.

`shell $ yarn json-autotranslate -i locales -s manual`

`Directory Structure`

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

`$3`

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

`$3`

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

`File Structure`

There are two ways that json-autotranslate can interpret files:

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

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

`$3`

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

`$3`

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

`Available Services`

As of this release, json-autotranslate offers five services:

You can select a service using the -s or --serviceoption. If you specify the--list-servicesflag, json-autotranslate will output a list of all available services.

`$3`

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

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

`$3`

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 json-autotranslate using the-c or --config option.

The value of the --configargument is a comma separated string with the following:appKey,formality,batchSize.

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

^Reference

`$3`

^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. See their pricing

`$3`

- 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": "*" } ] }`

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

`$3`

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

`Available Matchers`

You can select a matchers using the -m or --matcheroption. If you specify the--list-matchersflag, json-autotranslate will output a list of all available matchers.

`Available Options`

Contributing

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