Integration Utility

Access Continuous Localization With Crowdin


cli-client screenshot
Automate the process of updating your source files in your Crowdin project.
Download translations from Crowdin and automatically save them in the correct locations.
Upload all your existing translations to Crowdin in minutes.
Integrate Crowdin with GIT, SVN, Mercurial and more...
for Windows, Mac, and Linux
Free
Cross Platform
Open Source
Flexible
Universal

Crowdin-CLI

crowdin-cli is a command line tool that allows you to manage and synchronize your localization resources with your 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.


Installation

crowdin-cli can be installed via RubyGems or as a stand-alone Java application. There is also unofficial Python implementation which is available in Pip repository and as an .exe application for Windows.

Installing via RubyGems

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.

Installing as a Java application

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 as a Java application, complete these steps:

  • Download crowdin-cli.jar and save to your hard drive.
  • Check that you have Java 7 installed.
  • Add the crowdin-cli.jar file to your project directory.

Use the following method to run the application:

 java -jar crowdin-cli.jar help

This method works on both Windows and Unix machines.


Python version

Important: The Python version of Crowdin CLI tool has been developed and is being supported by the community.

The tool is claimed to be compatible with official configuration file format. Crowdin CLI Python is also available for Windows as a native application (see the Installation Instructions below).

Installation Instructions


Configuration

In general, you'll use crowdin-cli as follows:

  • Create a configuration file in your project root directory (we recommend you name it "crowdin.yaml").
  • Use the crowdin-cli script 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 use "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 the -c (or --config) option. See `crowdin-cli help` for more details. A sample configuration file is printed below. For more information on how to configure crowdin-cli, check the 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%'
        

Usage

Once the configuration file is created, you are ready to start using crowdin-cli to manage your localization resources and automate file synchronization.

Here's a list of 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.

Introduction

crowdin-cli uses a YAML configuration file, which contains a description of the resources to manage. That config is structured into sections, which contain the actual information for each set of files to be uploaded to Crowdin and the locations where their translations are stored. To use crowdin-cli, you should first write your YAML config, and then 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 different than crowdin.yaml).

The goal of this article is to help you obtain, setup, and execute crowdin-cli correctly for your project. Once you set up crowdin-cli properly you shouldn't need to revisit this page, unless you're starting another project.


Configuration File Structure

A valid crowdin-cli config file has the following structure:

  • Your Crowdin project credentials, project preferences and access information (they are at the head of YAML file).
  • Exactly one "files" element that contains child sections describing sets of the files you will manage.
  • Child sections of "files" node with two options (source and translation) that define filters for source files and instruction where to store translated files (also, where to look for translations when you want to upload them for the first time).

See Crowdin API Authentication article to learn where to find your project credentials.


Writing A Simple Configuration File

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

or

 $ crowdin-cli download

Get translations from Crowdin and put them to the right places:


General Configuration

The 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 are patterns you can use:

* (asterisk)

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 both the 'source' and in 'translation' patterns. When using ** in the 'translation' pattern it will always contain sub-path from 'source' for a certain file.
For example, you can use source: '/en/**/*.po' to upload all *.po files to Crowdin recursively. The 'translation' pattern will be '/%two_letters_code%/**/%original_file_name%'.

? (question mark)

Matches any one character.

[set]

Matches any one character in a set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

\ (backslash)

Escapes the next metacharacter.


Placeholders

crowdin-cli allows to use the following placeholders to put appropriate variables into the resulting file name:

Name Description
%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
%osx_code% OS X Locale identifier used to name ".lproj" 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 the 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%".


Usage of wildcards

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
        

Language Mapping

Often software projects have custom names for locale directories. crowdin-cli allows you to map your own languages to be understandable by Crowdin.

Let's say your locale directories named 'en', 'uk', 'fr', 'de'. All of them can be represented by the %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 a languages_mapping section to your file 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 the 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...


Ignoring directories

ignore:
          

From time to time there are directories you don't need to translate 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
          

Ignoring files

ignore:
          

From time to time there are files you don't need to translate 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
          

Multicolumn CSV

multilingual_spreadsheet: true

In a case where a CSV file must contain the translations for all target languages, you can use the 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

Saving directory structure on server

preserve_hierarchy: true

Example of file configuration using the preserve_hierarchy option:

project_identifier: test
api_key: KeepTheAPIkeySecret
base_url: https://api.crowdin.com
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

By default, project files will be represented in Crowdin as follows:

|-- foo.po
|-- bar.po

Using the option preserve_hierarchy, file structure in Crowdin will be the following:

|-- en
|
|-- foo.po
|-- bar.po

Changed strings update

The 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:

  • update_as_unapproved - preserve translations of changed strings and remove validations of those translations if they exist
  • update_without_changes - preserve translations and validations of changed strings.

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'
    

Translations upload

The command "upload translations" uploads existing translations to Crowdin. If no options specified, uploaded translations will be not approved, imported to Crowdin project even if they are duplicated and imported even if they are equal with the source strings.

The values are:

  • -l, --language=crowdin_language_code - defines the language translations should be uploaded to. By default translations are uploaded for all project's target languages.
  • --[no-]import-duplicates - defines whether to add translation if there is the same translation already existing in Crowdin project.
  • --[no-]import-eq-suggestions - defines whether to add translation if it is equal to source string in Crowdin project.
  • --[no-]auto-approve-imported - automatically approve uploaded translations.

Additional options for XML files

translate_content
optional
bool Defines whether to translate texts placed inside the tags. Acceptable values are: 0 or 1. Default is 1.
translate_attributes
optional
bool Defines whether to translate tags attributes. Acceptable values are: 0 or 1. Default is 1.
content_segmentation
optional
bool Defines whether to split long texts into smaller text segments. Acceptable values are: 0 or 1. Default is 1.
Important! This option disables the possibility to upload existing translations for XML files when enabled.
translatable_elements
optional
array This is an array of strings, where each item is the XPaths to DOM element that should be imported.
Sample path: /path/to/node or /path/to/attribute[@attr]
Note! If defined, the parameters "translate_content" and "translate_attributes" are not taken into account while importing.

Example of configuration file with additional parameters:

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: '/app/sample1.xml'
    translation: '/app/%locale%/%original_file_name%'
    translate_attributes: 1         
    translate_content: 0

  -
    source: '/app/sample2.xml'
    translation: '/app/%locale%/%original_file_name%'
    translatable_elements:
      - "/content/text"             # translatable texts are stored in "text" nodes of parent node "content"
      - "/content/text[@value]"     # translatable texts are stored in "value" attribute of "text" nodes
    

Escape quotes options for .properties file format

Defines whether single quote should be escaped by another single quote or backslash in exported translations. You can add escape_quote: per-file option.
Acceptable values are: 0, 1, 2, 3. Default is 3.

The values are:

  • 0 - do not escape single quote;
  • 1 - escape single quote by another single quote;
  • 2 - escape single quote by backslash;
  • 3 - escape single quote by another single quote only in strings containing variables ( {0} ).

Example of configuration file:

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: '/en/strings.properties'
    translation: '/%two_letters_code%/%original_file_name%'
    escape_quotes: 1      
    

Example Configurations

GetText Project

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'

Android Project

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



Seeking Assistance

Need help working with crowdin-cli or have any questions? Contact Support Team.