crowdin-cli is a command line tool that allows you to manage and synchronize your localization resources with Crowdin project. Console tool means that after installing it will not add an icon anywhere, it's not that sort of application. crowdin-cli is cross-platform and it runs in a terminal on Linux based and MacOS X operating systems or in cmd.exe on Windows. It's also open-source and it's source code available at GitHub.
crowdin-cli can be installed via RubyGems or as stand-alone Java application.
In order to run crowdin-cli you will need Ruby and RubyGems installed on your computer.
On Mac and Linux Ruby is probably installed already. If not, you can use this reference to learn how to install them.
On Windows machines you can use Ruby Installer.
When the Ruby is installed just type in console:
$ gem install crowdin-cli
crowdin-cli is installed. It's that simple.
We bundled crowdin-cli as a Java application to let you start using crowdin-cli easier. This method does not require installation. To get started with crowdin-cli Java application complete these steps:
Use the following method to run the application:
java -jar crowdin-cli.jar help
This method works on both Windows and Unix like machines.
In general, you'll use crowdin-cli as follows:
$ crowdin-cli coolaction
By default, crowdin-cli will look for a configuration file called crowdin.yaml. The coolaction indicates which command to execute. You can do "crowdin-cli help" to see all the available commands.
When calling `crowdin-cli` in terminal you should be in your project root directory otherwise you will have to specify configuration file path using -c (or --config) option, see `crowdin-cli help` for more details. Sample configuration file is printed below. For more information check on how to configure crowdin-cli check Configuration File section.
project_identifier: your-project-identifier api_key: 54e01e81--your-api-key--f6a2724a #can be found in your project settings page base_path: /home/office/source-code files: - source: '/_locales/en/*.json' #source files filter translation: '/_locales/%two_letters_code%/%original_file_name%' #where translations live - source: '/locale/en/**/*.po' translation: '/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%'
When the configuration file is created you are ready to start using crowdin-cli to manage your localization resources and automate files synchronization.
We listed most typical commands that crowdin-cli is used for:
$ crowdin-cli upload sources
Upload your source files to Crowdin.
$ crowdin-cli upload translations
Upload existing translations to Crowdin project (translations will be synchronized).
$ crowdin-cli download
Download latest translations from Crowdin.
$ crowdin-cli help upload
Get help on `upload` command.
$ crowdin-cli help upload sources
Get help on `upload sources` command.
Use help provided with an application to get more information about available commands and options.
crowdin-cli uses YAML configuration file that contain a description of the resources to manage. That config is structured into sections that contain the actual information on each set of files that should be uploaded to Crowdin and where their translations should be stored. So, to use crowdin-cli, you would first write your YAML config and then you would run the tool.
By default crowdin-cli will look for a config file named crowdin.yaml (so you don't have to specify the config name unless it is not crowdin.yaml).
The goal of this article is to help you obtain and correctly setup and execute crowdin-cli for your project. Once you setup crowdin-cli properly you shouldn't need to revisit this page, unless you're starting another project.
A valid crowdin-cli config file has the following structure:
See Crowdin API Authentication article to know where to find your project credentials.
project_identifier: your-project-identifier api_key: 54e01e81--your-api-key--f6a2724a #can be found in your project settings page base_path: /home/office/source-code files: - source: '/resources/en/*.json' #source files filter translation: '/resources/%two_letters_code%/%original_file_name%' #where translations live
To run the above configuration file and upload source files to Crowdin is only a matter of calling:
$ crowdin-cli upload sources
$ crowdin-cli download
Get translations from Crowdin and put them to the right places:
Example configuration provided above has 'source' and 'translation' attributes containing standard wildcards (also known as globbing patterns) to make it easier to work with multiple files.
Here's patterns you can use:
This wildcard represents any character in file or directory name. If you specified a "*.json" it will include all files like "messages.json", "about_us.json" and anything that ends with ".json".
** (doubled asterisk)
Matches any string recursively (including sub-directories). Note that you can use ** in 'source' and in 'translation' pattern. When using ** in 'translation' pattern it will always contain sub-path from 'source' for certain file.
Say, you can have source: '/en/**/*.po' to upload all *.po files to Crowdin recursively. 'translation' pattern will be '/%two_letters_code%/**/%original_file_name%'.
? (question mark)
Matches any one character.
Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).
Escapes the next metacharacter.
crowdin-cli allows to use the following placeholders to put appropriate variables into the resulting file name:
|%language%||Language name (i.e. Ukrainian)|
|%two_letters_code%||Language code ISO 639-1 (i.e. uk)|
|%three_letters_code%||Language code ISO 639-2/T (i.e. ukr)|
|%locale%||Locale (like uk-UA)|
|%locale_with_underscore%||Locale (i.e. uk_UA)|
|%original_file_name%||Original file name|
|%android_code%||Android Locale identifier used to name "values-" directories|
|%original_path%||Take parent folders names in Crowdin project to build file path in resulted bundle|
|%file_extension%||Original file extension|
|%file_name%||File name without extension|
You can also define the path for files in result archive by putting the slash (/) at the beginning of the pattern.
Your 'translation' option may look like: "/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%".
Structure of files and directories on the local machine:
- base_path | |-- folder | | | |-- 1.xml | |-- 1.txt | |-- 123.txt | |-- 123_test.txt | |-- a.txt | |-- a1.txt | |-- crowdin?test.txt | |-- crowdin_test.txt | |-- 1.xml |-- 1.txt |-- 123.txt |-- 123_test.txt |-- a.txt |-- a1.txt |-- crowdin?test.txt |-- crowdin_test.txt
Example 1. Usage of wildcards in the source path :
#........your project configuration........ files: - source: '/**/?[0-9].txt' #upload a1.txt, folder/a1.txt translation: '/**/%two_letters_code%_%original_file_name%' - source: '/**/*\?*.txt' #upload crowdin?test.txt, folder/crowdin?test.txt translation: '/**/%two_letters_code%_%original_file_name%' - source: '/**/[^0-2].txt' #upload 3.txt, folder/3.txt, a.txt, folder/a.txt (ignore 1.txt, folder/1.txt) translation: '/**/%two_letters_code%_%original_file_name%'
Example 2. Usage of wildcards for ignoring files:
#........your project configuration........ files: - source: '/**/*.*' #upload all files that the base_path contains translation: '/**/%two_letters_code%_%original_file_name%' ignore: - /**/?.txt #ignore 1.txt, a.txt, folder/1.txt, folder/a.txt - /**/[0-9].txt #ignore 1.txt, folder/1.txt - /**/*\?*.txt #ignore crowdin?test.txt, folder/crowdin?test.txt - /**/[0-9][0-9][0-9].txt #ignore 123.txt , folder/123.txt - /**/[0-9]*_*.txt #ignore 123_test.txt, folder/123_test.txt
Often software projects have custom names for locale directories. crowdin-cli allows you to map your own languages to understandable by Crowdin.
Let's say your locale directories named 'en', 'uk', 'fr', 'de'. All of them can be represented by %two_letters_code% placeholder. Still, you have one directory named 'zh_CH'. In order to make it work with crowdin-cli without changes in your project you can add languages_mapping section to your files set. See sample configuration below:
#........your project configuration........ files: - source: '/locale/en/**/*.po' translation: '/locale/%two_letters_code%/**/%original_file_name%' languages_mapping: two_letters_code: # crowdin_language_code: local_name 'zh-CN': 'zh_CH' 'fr-QC': 'fr'
Mapping format is the following: "crowdin_language_code" : "code_you_use". Check complete list of Crowdin language codes that can be used for mapping.
You can also override language codes for other placeholders like %android_code%, %locale% etc...
From time to time there are directories you don't need to be translated in Crowdin. Local per-directory rules can be added to the config file in your project.
files: - source: /locale/en/**/*.po translation: /locale/%two_letters_code%/**/%original_file_name% ignore: - /locale/en/templates - /locale/en/workflow
From time to time there are files you don't need to be translated in Crowdin. Local per-file rules can be added to the config file in your project.
files: - source: '/**/*.properties' translation: '/**/%file_name%_%two_letters_code%.%file_extension%' ignore: -/test/file.properties -/example.properties
In case when CSV file should contains translations to all target languages you can use per-file option multilingual_spreadsheet.
CSV file example:
identifier,source_phrase,context,Ukrainian,Russian,French ident1,Source 1,Context 1,,, ident2,Source 2,Context 2,,, ident3,Source 3,Context 3,,,
Configuration file example:
files: - source: multicolumn.csv translation: multicolumn.csv first_line_contains_header: true scheme: "identifier,source_phrase,context,uk,ru,fr" multilingual_spreadsheet: true
Example of file configuration using the preserve_hierarchy option:
project_identifier: test api_key: KeepTheAPIkeySecret base_url: http://api.crowdin.net base_path: /path/to/your/project preserve_hierarchy: true files: - source: /locale/en/**/*.po translation: /locale/%two_letters_code%/**/%original_file_name%
By default directories that do not contain any files for translation will not be created in Crowdin. For example:
- locale | |-- en | |-- foo.po |-- bar.po
Project files will be represented in Crowdin as the following by default:
|-- foo.po |-- bar.po
Using the option preserve_hierarchy file structure in Crowdin will be the following:
|-- en | |-- foo.po |-- bar.po
Parameter "update_option" is optional. If it is not set translations for changed strings will be lost. Useful for typo fixes and minor changes in source strings.
Depending on the value, "update_option" is used to preserve translations and preserve/remove validations of changed strings during file update. The values are:
Example of configuration file with update_option parameter:
project_identifier: your-project-identifier api_key: 54e01e81--your-api-key--f6a2724a #can be found in your project settings page base_path: /home/office/source-code files: - source: '/*.csv' translation: '/%three_letters_code%/%file_name%.csv' first_line_contains_header: true scheme: 'identifier,source_phrase,translation,context' update_option: 'update_as_unapproved' - source: '/**/*.xlsx' translation: '/%three_letters_code%/folder/%file_name%.xlsx' update_option: 'update_without_changes'
project_identifier: your-project-identifier api_key: 54e01e81--your-api-key--f6a2724a #can be found in your project settings page base_path: /home/website files: - source: '/locale/en/**/*.po' translation: '/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%' languages_mapping: two_letters_code: 'zh-CN': 'zh_CH' 'fr-QC': 'fr'
project_identifier: your-project-identifier api_key: 54e01e81--your-api-key--f6a2724a #can be found in your project settings page base_path: /home/android-app files: - source: '/res/values/*.xml' translation: '/res/values-%android_code%/%original_file_name%' languages_mapping: android_code: de: de # we need this mapping since Crowdin expects directories to be named like "values-uk-rUA" # according to specification instead of just "uk" ru: ru
Need help working with crowdin-cli or have any questions? Contact Support Team.