Crowdin CLI

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

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 other software

This is a cross-platform and it runs in a terminal on Linux based and macOS operating systems or in Command Prompt on Windows.

Status

What's new
Installation
Running the App
Configuration
Usage
Seeking Assistance
Contributing
Authors
License

What's New

CLI v3 has a lot of updates and improvements:

Available for Crowdin Enterprise
Multithreading for source and translation files upload
UX improvements: process indicators, loading states, emojis
Interactive generation of a configuration file
Bash/Zsh command completion
Improved help screen for commands
Improved configuration file validation
More import options for upload command
More export options for download command
Based on the new RESTful Crowdin API v2

More

Memory and CPU optimization
Translations download progress
HTTP Proxy support including authorization
Support Language Mapping configured on Crowdin
content_segmentation option support for xml, html, md, fm_md, fm_html, flsnp, docx, idml, dita
escape_special_characters option support for properties file
--dryrun option for translations upload
ignore pattern improvements
Added notification about new version
Added init alias to generate command
Bug fixes and other improvements
Complete list of changes: CHANGELOG.md

Note: for CLI v2 see the branch.

Installation

Requirements

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

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:

/etc/yum.repos.d/crowdin.repo:

[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

npm i -g @crowdin/cli

Standalone Version

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

Download for MacOS, Linux and Windows

Installation on Linux and macOS

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

Installation on Windows

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

Running the App

Use the following method to run the app:

crowdin

Alternative method:

java -jar crowdin-cli.jar

Configuration

Crowdin CLI uses a YAML configuration file that contains a description of the resources to manage: files to be uploaded into Crowdin and the locations of the corresponding translations.

To use Crowdin CLI, you should first generate your configuration file and then run the tool. By default, Crowdin CLI looks for a configuration file named crowdin.yaml or crowdin.yml (so you don’t have to specify the file name unless it’s different from crowdin.yaml).

To create the configuration file run the following command:

crowdin init

When calling Crowdin CLI in terminal make sure you are in your project root directory. Otherwise, you need to specify a configuration file path using --config option:

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

Sample configuration file:

"project_id": "12"
"api_token": "54e01--your-personal-token--2724a"
"base_path": "."
"base_url": "https://api.crowdin.com" # https://{organization-name}.crowdin.com

"preserve_hierarchy": true

"files": [
  {
    "source" : "/t1/**/*",
    "translation" : "/%two_letters_code%/%original_file_name%"
  }
]

For more information how to configure Crowdin CLI, check Configuration File article.

Usage

Once the configuration file is created, you can use Crowdin CLI to manage your localization resources and automate file synchronization.

General Commands

To display help information:

crowdin -h

crowdin <command> -h

To generate skeleton configuration file:

crowdin init

To check configuration file for general mistakes:

crowdin lint

To display a list of files uploaded to Crowdin:

crowdin list project

Uploading Resources

To upload source files to Crowdin:

crowdin upload sources

To upload single file without a configuration:

crowdin upload sources \
    -s path/to/your/file \
    -t file/export/pattern \
    -T personal-access-token \
    -i project-id \
    --base-url https://api.crowdin.com

Use placeholders to put appropriate variables.

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

crowdin upload sources --dryrun

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

crowdin upload translations

To show detailed information about the upload command:

crowdin upload --help

Downloading Translations

To download the latest translations from Crowdin:

crowdin download

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

crowdin download -l {language_code}

To display a list of the latest translations from Crowdin:

crowdin download --dryrun

To show detailed information about the download command:

crowdin download --help

Versions Management

There is no need to run specific command to create version branches if you use synchronization tool. The version branch is created automatically during the files 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

There is a possibility to manage (add, edit, delete) source strings for the following file types: CSV, RESX, JSON, Android XML, MACOSX, STRINGS, PROPERTIES.

Command	Description
`crowdin string list`	Show a list of source strings in the current project. You can use the `--verbose` option to see more information
`crowdin string add`	Create a new source string. Use `-h` option to see all possible command options
`crowdin string delete`	Delete source string
`crowdin string edit`	Edit existing source string

Translation and proofreading progress

To show translation and proofreading progress for a project use the following commands:

Command	Description
`crowdin status`	Show translation and proofreading progress for a project
`crowdin status translation`	Show only translation progress for a project
`crowdin status proofreading`	Show only proofreading progress for a project

Also, you can use the --verbose option to see more information.

Glossary management

There is a possibility to upload/download glossaries.

Command	Description
`crowdin glossary list`	Show a list of glossaries. Use —verbose to show term lists for glossaries
`crowdin glossary upload`	Upload glossary from a file (in TBX, CSV, or XLSX file format) either to the specified glossary or to a new one
`crowdin glossary download`	Download glossary file (in TBX, CSV, or XLSX file format) from the specified glossary

Translation memory management

To manage translation memories use the following commands:

Command	Description
`crowdin tm list`	Show a list of translation memories
`crowdin tm upload`	Upload translation memory from a file (Supported file formats: TMX, CSV, XLS/XLSX)
`crowdin tm download`	Download translation memory to a file

Seeking Assistance

If you find any problems or would like to suggest a feature, please read the How can I contribute section in our contributing guidelines.

Need help working with Crowdin CLI or have any questions? Contact Customer Success Service.

Contributing

If you want to contribute please read the Contributing guidelines.

Authors

Ihor Popyk (ihor.popyk@crowdin.com)
Yaroslav Medentsii (medentsiy.y@gmail.com)
Daniil Barabash (dbarabash42@gmail.com)

License

The Crowdin CLI is licensed under the MIT License. 
See the LICENSE.md file distributed with this work for additional 
information regarding copyright ownership.

Except as contained in the LICENSE file, the name(s) of the above copyright
holders shall not be used in advertising or otherwise to promote the sale,
use or other dealings in this Software without prior written authorization.

PauloBoaventura / crowdin-cli