Home

Awesome

<p align="center"> <a href="https://simplelocalize.io"> <img src="static/simplelocalize-git-banner.png" width="100%"> </a> </p> <h3 align="center">Translation Management for software projects</h3> <p align="center">The easiest way to manage translation files for web and mobile apps.</p> <p align="center"> <a href="https://simplelocalize.io/"> <img src="static/simplelocalize-git-hero.png"> </a> </p>

Tests Maintainability codecov

SimpleLocalize CLI is a command-line tool that allows you to manage translations in your software project, and it's a great tool for CI/CD pipelines and localization automation.

Installation

The installation process is automated by command-line scripts. Both scripts for Windows (PowerShell) and macOS/Linux/Windows downloads a binary file with CLI, copies it to user files and makes it available to run anywhere in the system from a command-line.

# macOs / Linux / Windows (WSL)
curl -s https://get.simplelocalize.io/2.7/install | bash

# Windows (PowerShell)
. { iwr -useb https://get.simplelocalize.io/2.7/install-windows } | iex;

To change or update the CLI version, run the installation script with the desired version number in the URL, e.g.:

See releases for the list of available versions.

Usage

The command-line tool offers several commands to execute. All of them requires Project API Key that is unique for each project. You can set apiKey in simplelocalize.yml configuration file, pass it as parameter with --apiKey or set it by environment variable SIMPLELOCALIZE_API_KEY.

simplelocalize [command] ...parameters

Available commands:

Create configuration file

Command creates a sample configuration file in the current directory. The configuration file simplifies the usage of the command-line tool by providing a default configuration for the project and allowing to omit some parameters.

simplelocalize init

Upload translations

Upload command takes your local files and uploads them to SimpleLocalize. You can specify a path to the file or use placeholders to upload many files at once. A good practise is to upload only source translations instead of uploading all translations on each run. You can use {lang} placeholder to specify language or locale and {ns} placeholder to specify namespace, e.g.: ./src/translations/{lang}/{ns}.json.

simplelocalize upload 
  --apiKey <PROJECT_API_KEY>
  --uploadPath <UPLOAD_PATH_PATTERN>
  --uploadFormat <UPLOAD_FORMAT>

Upload format is a format of the file(s) with translations. See available upload formats

Additional parameters:

Since version 2.7 you can skip 'upload' part in the parameters names, e.g.: --path instead of --uploadPath.

Learn more about upload translations command.

Example: One file with multiple languages

.
└── locales
    └── messages.json

Command:

simplelocalize upload 
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./locales/messages.json
  --uploadFormat multi-language-json

Example: One file per language

In this example we upload only source translations from ./en/messages.json and uses --uploadLanguageKey en-GB to specify language key for the uploaded file for the Translation Editor. It's a recommended way to upload source translations.

.
├── ca
│   └── messages.json
├── en
│   └── messages.json
└── es
    └── messages.json

Command:

simplelocalize upload 
  --apiKey <PROJECT_API_KEY>
  --uploadPath ./en/index.json
  --uploadLanguageKey en-GB
  --uploadFormat single-language-json

Example: One file per language using placeholders

In this example we use {lang} placeholder to upload many files at once and specify language key for each file. It's not a recommended way to upload source translations, as it uploads more files than necessary.

.
├── ca
│   └── index.json
├── en
│   └── index.json
└── es
    └── index.json

Command:

simplelocalize upload 
  --apiKey <PROJECT_API_KEY>
  --uploadPath /{lang}/index.json
  --uploadFormat single-language-json

Example: One file per language and namespace

In this example we use {ns} placeholder to upload many files at once for the English language. We used --uploadLanguageKey en-GB to specify language key for the uploaded file for the Translation Editor.

.
├── italian
│   ├── common.json
│   └── home.json
├── english
│   ├── common.json
│   └── home.json
└── spanish
    ├── common.json
    └── home.json

Command:

simplelocalize upload 
  --apiKey <PROJECT_API_KEY>
  --uploadPath /english/{ns}.json
  --uploadLanguageKey en-GB
  --uploadFormat single-language-json

Download translations

Download works similarly to the upload command, but this time it exports translation files from the Translation Editor to your local files.

simplelocalize download 
  --apiKey <PROJECT_API_KEY>
  --downloadPath <DOWNLOAD_PATH_PATTERN>
  --downloadFormat <DOWNLOAD_FORMAT>

Download format is a format of the file(s) with translations. See available upload formats

Example

Same as before you can use {lang} and {ns} placeholders to download many files at once and specify language keys that should be downloaded, eg.:

simplelocalize download 
  --apiKey <PROJECT_API_KEY>
  --downloadPath ./src/{ns}/messages_{lang}.json
  --downloadFormat single-language-json
  --downloadLanguageKey en,de,fr

Additional parameters:

Since version 2.7 you can skip 'download' part in the parameters names, e.g.: --path instead of --downloadPath.

Learn more about download translations command.

Auto-translate strings

Auto-translate command starts auto-translation tasks for all languages in the project or for languages specified in --languageKeys parameter. Auto-translation configuration is taken from the last auto-translation job in the project for the given language.

simplelocalize auto-translate --apiKey <PROJECT_API_KEY>

Additional parameters:

Translation Hosting: Publish translations

It publishes translation to Translation Hosting. It behaves exactly the same as publish buttons in the SimpleLocalize (Hosting tab).

Publishes translations from Translation Editor to the _latest environment.

simplelocalize publish --apiKey <PROJECT_API_KEY> --environment _latest

Publishes translations from the _latest environment to _production environment.

simplelocalize publish --apiKey <PROJECT_API_KEY> --environment _production

Translation Hosting: Pull resources

Downloads all translation hosting files to given directory in --pullPath parameter. It overwrites existing files and creates subdirectories if necessary.

Pulls translations from the _latest environment.

simplelocalize pull --apiKey <PROJECT_API_KEY> --pullPath ./hosting/ --environment _latest

Pulls translations from the _production environment.

simplelocalize pull --apiKey <PROJECT_API_KEY> --pullPath ./hosting/ --environment _production

If you would like to filter files which should be downloaded you can use --filterRegex param, e.g.: --filterRegex '__index.json' will download only __index.json file.

Get project details

Command gets project details and prints them to the console.

simplelocalize status --apiKey <PROJECT_API_KEY>

Purge translations

Command removes all translations, translation keys and languages from Translation Editor.

simplelocalize purge --apiKey <PROJECT_API_KEY>

Additional parameters:

Extract translation keys

Extract command finds translation keys and translations from project source code at <SEARCH_DIRECTORY> and exports them to extraction.json file that uses simplelocalize-json file format.

simplelocalize extract 
  --searchDir <SEARCH_DIRECTOR>
  --projectType <PROJECT_TYPE>

See available project types.

Configuration file

Use configuration file to simplify your bash command. Arguments used in command always override properties set in the configuration file. By default, SimpleLocalize will load configuration from file named simplelocalize.yml. You can load configuration from different location by using a -c parameters.

# Load default simplelocalize.yml file
simplelocalize upload

# Use configuration file at custom location
simplelocalize -c my-configuration.yml upload

Sample configuration file

Filename: simplelocalize.yml

# Get started with CLI: https://simplelocalize.io/docs/cli/get-started/
# Available formats: https://simplelocalize.io/docs/general/file-formats/
# Available import/export options: https://simplelocalize.io/docs/general/options/
# Support: contact@simplelocalize.io

# Project API Key
apiKey: API_KEY

# Properties used by 'upload' command
uploadPath: ./source-translations/messages_en.json
uploadLanguageKey: en-GB
uploadFormat: single-language-json
uploadOptions:
  # by default, the 'upload' command only adds new keys and fills empty translations, 
  # add this option to overwrite existing translations with values from the uploaded file
  - REPLACE_TRANSLATION_IF_FOUND 

# Properties used by 'download' command
downloadPath: ./output-translations/messages_{lang}.json
downloadLanguageKey: ['de-DE', 'fr-FR', 'pl-PL']
downloadFormat: single-language-json
downloadOptions:
  - WRITE_NESTED

# Properties used by 'extract' command
searchDir: ./src
projectType: yahoo/react-intl
ignoreKeys:
  - 'WELCOME'
  - 'ABOUT-US'

# Properties used by 'pull' and 'publish' command    
pullPath: ./src/hosting/
environment: '_production' # or '_latest', or 'my_custom'

Proxy support

SimpleLocalize CLI supports HTTP and HTTPS proxies, and it respects the http_proxy, https_proxy environment variables.

Here are some examples of how to set proxy environment variables in Linux and macOS:

export http_proxy=http://someproxy.com
export http_proxy=http://someproxy.com:8080
export http_proxy=http://user:password@someproxy.com:8080

Support

Please refer to the official SimpleLocalize documentation. That should help you troubleshoot common issues. For additional help, you can reach out to us on one of these channels:

License

See LICENSE for more details.