The easiest way to manage translation files for web and mobile apps.
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.
- Upload and download translations. The main purpose of the command-line tool is to upload and download translation files from Translation Editor to your project.
- Auto-translate strings. Start auto-translation jobs from the command-line and get translated strings in a few minutes.
- Hosted translations management. Push and pull translations from Translation Hosting to your project using the command-line.
- GitHub Actions support. Use SimpleLocalize CLI in your GitHub Actions workflows.
- Check project status. Get project details from the command-line and check if your translations are up-to-date.
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.6/install | bash
# Windows (PowerShell)
. { iwr -useb https://get.simplelocalize.io/2.6/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.
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 filestatus
- gets translation project detailsupload
- uploads translation files or translation keysdownload
- downloads translation filessync
- uploads translation files and downloads translation filesauto-translate
- starts auto-translation jobspull
- downloads translation files from Translation Hostingpublish
- publishes translations to Translation Hostingpurge
- removes all translation, translation keys and languages from Translation Editorextract
- 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.
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
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:
--overwrite
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. E.g.:--uploadOptions TRIM_LEADING_TRAILING_SPACES
. To pass multiple options, use comma as a separator.
Learn more about upload translations command.
.
└── locales
└── messages.json
Command:
simplelocalize upload
--apiKey <PROJECT_API_KEY>
--uploadPath /locales/messages.json
--uploadFormat multi-language-json
.
├── ca
│ └── index.json
├── en
│ └── index.json
└── es
└── index.json
Command:
simplelocalize upload
--apiKey <PROJECT_API_KEY>
--uploadPath /{lang}/index.json
--uploadFormat single-language-json
.
├── 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
Command downloads translation files from the Translation Editor to the 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 command starts auto-translation jobs 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:
--languageKeys
allows you to specify project language keys to auto-translate, e.g.:--languageKeys en,de,fr
.
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
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.
Command gets project details and prints them to the console.
simplelocalize status --apiKey <PROJECT_API_KEY>
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.
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 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>
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
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'
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
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:
- GitHub (Bug and issue reports)
- Email (General support)
- Changelog (Product updates)
- YouTube (How-to tutorials)
See LICENSE for more details.