Integration Utility

Reach Continuous Localization With Crowdin


cli-client screenshot
Automate your source files updating in Crowdin project.
Download translations from Crowdin and put them to the right places.
Upload all existing translations to Crowdin withing 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 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 stand-alone Java application.

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

  • Download crowdin-cli.jar and save to you disk.
  • Check that you have Java 7 installed.
  • Put 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 like machines.


Configuration

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

  • Create a configuration file in your project root directory (we recommend you to 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 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%'
        

Usage

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.

Introduction

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.


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 know 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

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:

* (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 '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.

[set]

Matches any one character in 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
%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%".


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
        

Languages Mapping

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...


Ignoring directories

ignore:
          

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
          

Ignoring files

ignore:
          

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
          

Multicolumn CSV

multilingual_spreadsheet: true

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

Saving structure of directories on server

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

Changed strings update

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'
    

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.