Console Client (CLI)

Crowdin CLI is a command line tool that allows you to manage and synchronize your localization resources with your Crowdin project:

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

This is a cross-platform and it runs in a terminal on Linux based and macOS operating systems or in Command Prompt on Windows. It’s also open-source and it’s source code available at GitHub.

Requirements

Check that you have Java 8 or newer installed. Type java -version command in the terminal (Command Prompt on Windows) to check Java version. For example, java version “1.8.0_212” means that you have Java 8 Update 212 installed.

If you don’t have Java installed, download it from Oracle’s website.

Installation

Homebrew for macOS

To install the Crowdin CLI with homebrew (the package manager for macOS):

$ brew tap crowdin/crowdin

$ brew install crowdin@3

Windows

Download and run installer for Windows.

Debian

We sign all our packages with the Crowdin Signing Key.

Download and install the public signing key:

wget -qO - https://artifacts.crowdin.com/repo/GPG-KEY-crowdin | sudo apt-key add -

Using the following command, create the crowdin.list file in the /etc/apt/sources.list.d directory:

echo "deb https://artifacts.crowdin.com/repo/deb/ /" > /etc/apt/sources.list.d/crowdin.list

And your repository is ready for use. You can install the Crowdin CLI Debian package with:

sudo apt-get update && sudo apt-get install crowdin3

To install the Crowdin CLI manually:

$ wget https://artifacts.crowdin.com/repo/deb/crowdin3.deb -O crowdin.deb
$ sudo dpkg -i crowdin.deb

RPM

We sign all our packages with the Crowdin Signing Key.

Download and install the public signing key:

rpm --import https://artifacts.crowdin.com/repo/GPG-KEY-crowdin

Installing from the RPM repository

Create a file called crowdin.repo in the /etc/yum.repos.d directory containing:

[crowdin]
name=Crowdin repository
baseurl=https://artifacts.crowdin.com/repo/rpm
gpgcheck=1
gpgkey=https://artifacts.crowdin.com/repo/GPG-KEY-crowdin
enabled=1

And your repository is ready for use. You can now install Crowdin CLI with one of the following commands:

sudo yum install crowdin3
sudo dnf install crowdin3

To install the Crowdin CLI manually:

$ wget https://artifacts.crowdin.com/repo/rpm/crowdin3.rpm -O crowdin.rpm
$ sudo rpm -U crowdin3.rpm

Arch Linux

Visit the Crowdin CLI package page on Arch Linux user repository.

NPM

Installing from the NPM repository

npm i -g @crowdin/cli

Standalone Version

Crowdin CLI can be installed as a stand-alone Java application.

Installation on Linux and macOS

1. Download crowdin-cli.zip using the button above
2. Unpack it
3. Run ./install-crowdin-cli.sh in the terminal with sudo rights in order to add crowdin command to your terminal

Installation on Windows

1. Download crowdin-cli.zip using the button above
2. Extract it's content to the place where you want Crowdin CLI to be stored
3. Open Command Prompt as an Administrator
1. Click Start
2. In the Start Search box, type cmd, and then press Ctrl+Shift+Enter
3. If the User Account Control dialog box appears, confirm that the action it displays is what you want, and then click Continue
4. Run setup-crowdin.bat script in order to add crowdin command to the Command Prompt
5. Restart your Command Prompt

Using Crowdin CLI with Proxy Server

Crowdin CLI provides a possibility to work with a proxy server. Each time you run a command, Crowdin CLI checks whether the operating system has the configured environment variables.

Supported environment variables:

HTTP_PROXY_HOST – the name or the IP address of the host at which the proxy server is located
HTTP_PROXY_PORT – the port used by the proxy server for listening
HTTP_PROXY_USER – the username used for authentication on a proxy server
HTTP_PROXY_PASSWORD – the password used for authentication on a proxy server

Running the App

Use the following method to run the app:

$ crowdin

Alternative method:

$ java -jar crowdin-cli.jar

Configuration

To use Crowdin CLI you need to have a configuration file. We recommend to name it crowdin.yml. You can create it running the command:

$ crowdin init

When calling Crowdin CLI in terminal you should be in your project root directory. Otherwise, you will have to specify a configuration file path using the --config option:

$ crowdin upload sources --config /path/to/your/config/file

Run crowdin help to get more details regarding other commands.

Sample configuration file:

"project_id": "projectId"
"api_token": "personal-access-token"
"base_path": "."                        # path to your project directory on a local machine
"base_url": "https://api.crowdin.com"       # https://{organization-name}.crowdin.com for Crowdin Enterprise
"preserve_hierarchy": true

"files": [
  {
      "source": "/en/**/*.json",                                          #source files filter
      "translation": "/%two_letters_code%/**/%original_file_name%"        #where translations are stored
  }
]

For more information on how to configure Crowdin CLI, read the Configuration File article.

Usage

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

General Commands

To show help information about Crowdin CLI:

$ crowdin help

To generate a skeleton configuration file:

$ crowdin init

To check configuration file for general mistakes:

$ crowdin lint

To display a list of uploaded files to Crowdin:

$ crowdin list project

Uploading Sources

To upload source files to Crowdin:

$ crowdin upload sources

To specify the target languages the source files shouldn’t be translated into:

$ crowdin upload sources --excluded-language uk fr

To upload a single file without configuration:

$ crowdin upload sources -s "..." -t "..." -T personal-token -i project-id

For Crowdin Enterprise:

$ crowdin upload sources -s "..." -t "..." -T personal-token -i project-id --base-url 'your-organization-url'

Use placeholders to put appropriate variables.

To display a list of files that will be uploaded to Crowdin:

$ crowdin upload sources --dryrun

To delete obsolete files from a Crowdin project:

$ crowdin upload sources --delete-obsolete

To upload existing translations to Crowdin (translations will be synchronized):

$ crowdin upload translations

To show a detailed information about the upload command:

$ crowdin upload --help

To add existing or new labels to the source strings:

$ crowdin upload sources -s "..." -t "..." --label "main-menu" --label "application"

Read more about Labels.

Downloading Sources

To download source files from Crowdin:

$ crowdin download sources

Downloading Translations

To download latest translations from Crowdin:

$ crowdin download

To download latest translations for the specific language (language codes):

$ crowdin download -l {language_code}

To display a list of latest translations from Crowdin:

$ crowdin download --dryrun

To show a detailed information about the download command:

$ crowdin download --help

Downloading Translations to a Target File

Regardless of the initial source file format, you can download translation files in the Android XML, iOS Strings, and XLIFF formats.

It’s beneficial when localizing mobile app content or when the final translation file format differs from the initial source format. You can use beforehand generated source files or send strings to your Crowdin project directly from design tools. When translations are finished, you can download them in the needed format and easily integrate them into the codebase.

To launch custom exporters and download files in the necessary format:

$ crowdin download targets <name>

Configuration

Add the targets section to your crowdin.yml configuration file with the following structure:

targets: [
  {
    name: "android",
    files: [
      {
        file: "targets/%two_letters_code%/android.xml",
        sources: [
            "file.xlsx"
        ],
        labels: [
            "mobile",
            "ui"
        ]
      }
    ]
  }
]

• name - the name of your target. Will be used for downloading specific targets.
• files - the section that describes the resulting files that appear in your system after the download. Each target supports the downloading of multiple files.
• file - the resulting file pattern. Currently supported file formats are the following: Android XML (.xml), iOS Strings (.strings), and XLIFF. New file formats are coming soon.
• sources - the source files in Crowdin, whose translations should be exported. Alternatively, you can specify either branches or directories.
• labels - Labels for the strings filtering (Optional).

As a result, the file.xlsx translations (filtered by labels mobile and ui) will be downloaded to targets/%two_letters_code%/android.xml file.

Downloading Pseudo-localization

You can configure and download pseudo-localized translation files.

To download an archive with pseudo-localized translation files:

$ crowdin download --pseudo

Configuration

Add the pseudo_localization section to your crowdin.yml configuration file with the following structure:

pseudo_localization: {
  length_correction: 25,
  prefix: "",
  suffix: "",
  character_transformation: "cyrillic"
}

Versions Management

You can manage (add, delete) version branches in a project.

To create a new version branch:

$ crowdin branch add {branch_name}

To delete a version branch:

$ crowdin branch delete {branch_name}

Also, you can create version branches during the file upload.

To upload source files to the specified version branch:

$ crowdin upload sources -b {branch_name}

To upload translations to the specified version branch:

$ crowdin upload translations -b {branch_name}

To download translations from the specified version branch:

$ crowdin download -b {branch_name}

Source Strings Management

You can manage (add, edit, delete) source strings for the following file types: CSV, RESX, JSON, Android XML, iOS strings, PROPERTIES.

To show a list of source strings in the current project (use the --verbose option to see more information):

$ crowdin string list

To show a list of source strings for a specified version branch in a project:

$ crowdin string list --branch {branch_name}

To create a new source string (use --label to add labels to the strings you’re creating):

$ crowdin string add

To delete source string:

$ crowdin string delete

To edit existing source string (use --label to add labels to the strings you’re editing):

$ crowdin string edit

Use the -h option to see all possible command options.

Translation and Proofreading Progress

You can check the translation and proofreading progress for a project using the following commands.

To show both translation and proofreading progress for a project:

$ crowdin status

To show both translation and proofreading progress for a specified version branch in a project:

$ crowdin status --branch {branch_name}

To show translation progress for a project:

$ crowdin status translation

To show proofreading progress for a project:

$ crowdin status proofreading

Also, you can use the --verbose option to see more information. Use -h option to see all possible command options.

Glossary Management

You can upload and download glossaries.

To show a list of glossaries (use the --verbose option to show term lists for glossaries):

$ crowdin glossary list

To upload glossary from a file (in TBX file format) either to the specified glossary or to a new one:

$ crowdin glossary upload

To upload glossary from a file (in CSV or XLS/XLSX file format) either to the specified glossary or to a new one:

$ crowdin glossary upload <file> --scheme term_en=0 --scheme description_en=1 --scheme partOfSpeech_en=2 --first-line-contains-header

To form the scheme for your CSV or XLS/XLSX glossary file, use the following constants:

term_{language_code} – Column contains terms.
{column_number} – Column number. Numbering starts from 0.
description_{language_code} – Column contains term descriptions.
partOfSpeech_{language_code} – Column contains part of speech for terms.
where {language_code} – Language code for the specified language. See the full list of Supported Languages.
--first-line-contains-header – used to skip the import of the first row (header).

To download glossary to a file (in TBX, CSV, or XLS/XLSX file format) from the specified glossary:

$ crowdin glossary download

Translation Memory Management

You can upload and download translation memories.

To show a list of translation memories:

$ crowdin tm list

To upload translation memory from a file (in TMX file format) either to the specified translation memory or to a new one:

$ crowdin tm upload

To upload translation memory from a file (in CSV or XLS/XLSX file format) either to the specified translation memory or to a new one:

$ crowdin tm upload <file> --scheme en=0 --scheme fr=1 --first-line-contains-header

To form the scheme for your CSV or XLS/XLSX translation memory file, use the following constants:

{language_code} – Column contains translation memory elements for the specified language.
{column_number} – Column number. Numbering starts from 0.
where {language_code} – Language code for the specified language. See the full list of Supported Languages.
--first-line-contains-header – used to skip the import of the first row (header).

To download translation memory to a file (in TMX, CSV, or XLS/XLSX file format) from the specified translation memory:

$ crowdin tm download

Pre-translation

You can pre-translate source files that match the wild-card pattern and are stored in the current Crowdin project. You can use the pre-translation via TM or MT.

To run pre-translation via TM:

$ crowdin pre-translate --method tm

To run pre-translation via MT:

$ crowdin pre-translate --method mt --engine-id=...

Use -h option to see all possible command options.

List Project Target Languages

You can list target languages that are used in the current project.

To display a list of target languages:

$ crowdin list languages

Use -h option to see all possible command options.

See Also

• Configuration File
• Crowdin CLI Wiki