/simplelocalize-cli

Command-line tool for SimpleLocalize

Primary LanguageJavaMIT LicenseMIT

Tests Maintainability codecov

What it does?

SimpleLocalize command-line tool allows you to:

  • upload and download translations,
  • auto-translate translations,
  • publish and push Translation Hosting translations,
  • extract translation keys from your project files,
  • and more...

It is a great tool for CI/CD pipelines and localization automation.

Github Actions support

SimpleLocalize CLI is also availabe as a Github Action here: https://github.com/simplelocalize/github-action-cli

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.5/install | bash

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

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

  • https://get.simplelocalize.io/2.0.6/install installs version 2.0.6 on macOS/Linux/Windows (WSL)
  • https://get.simplelocalize.io/2.0.6/install-windows installs version 2.0.6 on Windows (PowerShell)

See releases for the list of available versions.

Usage

The command-line tool offers several commands to execute. All of them requires --apiKey YOUR_API_KEY parameter that is unique for each project.

simplelocalize [command] ...parameters

Available commands:

  • init - creates a sample configuration file
  • status - gets translation project details
  • upload - uploads translation files or translation keys
  • download - downloads translation files
  • sync - uploads translation files and downloads translation files
  • auto-translate - starts auto-translation jobs
  • pull - downloads translation files from Translation Hosting
  • publish - publishes translations to Translation Hosting
  • purge - removes all translation, translation keys and languages from Translation Editor
  • extract - finds and extracts translation keys in your project files

Use --help parameter to get more information about the command and its parameters or check documentation.

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

Command uploads translation files from given <UPLOAD_PATH_PATTERN> to Translation Editor, e.g.: ./src/translations/messages.json.

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

You can use {lang} placeholder to specify language or locale and {ns} placeholder to specify namespace, e.g.: ./src/translations/{lang}/{ns}.json.

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

Additional parameters:

  • --replace allows you to replace existing translations with new ones.
  • --dryRun allows you to check what translation files will be uploaded without actually uploading them.
  • --uploadOptions allows you to pass additional options to the upload command. Eg.: --uploadOptions TRIM_LEADING_TRAILING_SPACES. To pass multiple options, use comma as a separator.

Learn more about upload translations command.

Download translations

Command downloads translation files from Translation Editor to given <DOWNLOAD_PATH_PATTERN>, e.g.: ./src/translations/messages.json.

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

You can use {lang} placeholder to specify language or locale and {ns} placeholder to specify namespace, e.g.: ./src/translations/{lang}/{ns}.json.

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

Additional parameters:

  • --downloadOptions allows you to pass additional options to the download command. Eg.: --downloadOptions WRITE_NESTED.
  • --downloadSort allows you to sort translations in the downloaded file. Eg.: --downloadSort NEWEST_KEYS_FIRST. Available options: NEWEST_KEYS_FIRST, NEWEST_KEYS_LAST, NAMESPACES, IMPORT_ORDER.

Learn more about download translations command.

Auto-translate strings

Auto-translate command starts auto-translation jobs.

simplelocalize auto-translate --apiKey <PROJECT_API_KEY>

Additional parameters:

  • --languageKeys allows you to specify languages to auto-translate. Eg.: --languageKeys en,de,fr.

Usage examples

Below, you can find some examples of using SimpleLocalize CLI.

Example: One file with translations

.
└── locales
    └── messages.json

Command:

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

Example: Single file in multiple language directories

.
├── 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: Multiple files in multiple language directories

.
├── ca
│   ├── common.json
│   └── home.json
├── en
│   ├── common.json
│   └── home.json
└── es
    ├── common.json
    └── home.json

Command:

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

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>

Sync translations

Sync command combines upload and download command executions.

simplelocalize sync 
  --apiKey <PROJECT_API_KEY>
  --downloadPath <DOWNLOAD_PATH>
  --downloadFormat <DOWNLOAD_FORMAT>
  --downloadOptions <DOWNLOAD_OPTIONS>
  --uploadPath <UPLOAD_PATH>
  --uploadFormat <UPLOAD_FORMAT>
  --uploadOptions <UPLOAD_OPTIONS>

--downloadOptions and --uploadOptions parameters are optional.

Purge translations

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

simplelocalize purge --apiKey <PROJECT_API_KEY>

Additional parameters:

  • --force allows you to skip confirmation prompt.

Extract translation keys

Extract command finds and upload translation keys from project source code at <SEARCH_DIRECTORY> to SimpleLocalize.

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

See available project types.

Configuration file

Use configuration file in order 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: ./src/{lang}/{ns}.json
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: ./src/{ns}/messages_{lang}.json
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

Documentation

Visit simplelocalize.io/docs/cli/get-started/ to get more information about SimpleLocalize CLI.

License

Check LICENSE.md file