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://github.com/simplelocalize/simplelocalize-cli"> <img src="static/simplelocalize-git-hero.png"> </a> </p>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.
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.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.
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 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.
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:
--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.
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
Download translations
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 strings
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
.
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 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>
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: ./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
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:
- GitHub (Bug and issue reports)
- Email (General support)
- Changelog (Product updates)
- YouTube (How-to tutorials)
License
See LICENSE for more details.