json-translate

CLI tool to translate JSON files automatically using external translation services like DeepL or AWS Translate

Normally, multilingual projects base their translations on JSON files with different levels of nesting. This small project makes it easy to generate new files for new languages while keeping the same structure.

json_translate deepl /path/to/input-file.json FR

# Input file:                    Output file:
# {                              {
#   "welcome": "Welcome!",         "welcome": "Bienvenue!",
#   "questions": {                 "questions": {
#     "sure": "Are you sure?"        "sure": "Êtes-vous sûr?"
#    }                             }
# }                              }

The supported languages depends on the service used:

• DeepL supported languages.
• AWS supported languages.

Install

1. Install dependencies:

   pip install json-translate

2. To define the environmental variables, create an .env file in the root directory with the required variables, which will vary depending on the external service you will use:

   EXAMPLE_VARIABLE_NAME=example_variable_value
   

   You can also define them directly in your environment without having to create the .env file, it's up to you.

Use with DeepL

You can use DeepL with a free account or with a paid account.

• Free account: You can get a free deepl developer account in https://www.deepl.com/pro-checkout/account (Credit card needed). Once you have registered, you must include your auth key in the .env file:

  DEEPL_AUTH_KEY=your-key-here
  

• Paid account: If you have a paid account, in addition to including your auth key, you must include the API endpoint in the file.

  DEEPL_AUTH_KEY=your-key-here
  DEEPL_API_ENDPOINT=https://api.deepl.com/v2/translate
  

Use with AWS Translate

Login on your AWS account and obtain your credentials and place them in the .env file:

AWS_REGION_NAME=your-aws-region
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret

How to use

Execute the command with the service, the file path and the language you want to generate:

json_translate <service> <source> <locale>
# Example: json_translate aws locales/en.json ES

The script will create an es.json file in the same folder as the source file.

Required parameters

service               Translation service to use. Can be "deepl" or "aws"
source                Path to source file (must be a json file)
target_locale         Translation target language code

Optional parameters

-sl, --source-locale  Source language translating from (Required for AWS).
-o, --output          Output file name. Defaults to "<target_locale>.json" (ex: en.json)
-e, --extend          Extend the existing translation file (defined by <output>)
-s, --sleep           Sleep time between API calls. Defaults to 0.01 (seconds)
-i, --indent          Output file indentation spaces. Defaults to 2
--encoding            Input & output file encoding. Defaults to UTF-8
--skip                Keys to skip in the json file (they won't be translated)
--log                 Display translations as they are being translated
--override            Force override on output file

DeepL options

-g, --glossary        Glossary ID to use when translating (Optional)

AWS Translate options

--formality           Set formality level to FORMAL
--profanity           Mask profane words and phrases

Note that sleep, indentation and encoding can also be defined with variables in the .env file but they are overwritten with the values of the command:

SLEEP_BETWEEN_API_CALLS=0.01
INDENTATION_DEFAULT=2
ENCODING=utf-8

Example file

Translate the example file /tests/data/en_US.json to spanish:

json_translate deepl tests/data/en_US.json ES --skip lorem ipsum --log

DeepL API usage

You can check your API usage with

curl -H "Authorization: DeepL-Auth-Key YOUR-API-KEY-HERE" https://api-free.deepl.com/v2/usage

Contributing

See the contributing guide for detailed instructions on how to get started.

License

This repository is available under GNU LESSER GENERAL PUBLIC LICENSE v2.1 (LGPL).