Crowdin CLI

A helper tool to sync translation messages with Crowdin, using @formatjs/cli for message extraction.

Installation

npm install @mollie/crowdin-cli
# or
yarn add @mollie/crowdin-cli

How to Use (v4)

The CLI now supports only three commands: sync, delete-branch, and delete-stale-branches.

1. Authentication

Create a .env file in your project root and add your Crowdin personal access token:

CROWDIN_PERSONAL_ACCESS_TOKEN=your-token

2. Example Scripts

Add these scripts to your package.json (replace <your-project-id> with your actual Crowdin project ID):

{
  "crowdin:sync": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id>",
  "crowdin:upload": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-download",
  "crowdin:download": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-upload",
  "crowdin:delete-branch": "mollie-crowdin delete-branch --project-id <your-project-id>",
  "crowdin:delete-stale-branches": "mollie-crowdin delete-stale-branches --project-id <your-project-id>"
}

• Use --skip-download to only upload messages.
• Use --skip-upload to only download translations.

3. Command Reference

sync <glob>

Scan the directory for new messages and upload them to Crowdin, optionally downloading translations and running pre-translation.

Common options:

• --typescript — Write to TypeScript files (.ts)
• --skip-upload — Skip the upload step (download only)
• --skip-download — Skip the download step (upload only)
• --branch-name, -b <name> — Crowdin branch name (defaults to current Git branch)
• --project-id, -pi <id> — Required. Crowdin project ID
• --languages, -l <languages> — Comma-separated list of target languages (e.g. de,fr,nl). If not provided, all enabled languages are used (i.e., all languages enabled in your Crowdin project).
• --pre-translate, -pt — Whether to generate pre-translations for the uploaded files
• --pre-translate-languages, -ptl <languages...> — Comma-separated list of languages to pre-translate. If not provided, all enabled languages are used (i.e., all languages enabled in your Crowdin project).
• --pre-translate-method, -ptm <method> — Pre-translate method to use. Options: 'ai', 'mt', 'tm'
• --pre-translate-engine-id, -ptei <id> — Engine ID for machine pre-translation
• --pre-translate-prompt-id, -ptpi <id> — AI prompt ID for pre-translation
• --create-tasks, -t — Type of tasks to create

delete-branch

Delete a branch in Crowdin.

• --branch-name, -b <name> — Crowdin branch to be deleted
• --delete-tasks, -dt — Whether to delete any associated tasks
• --project-id, -pi <id> — Required. Crowdin project ID

delete-stale-branches

Delete branches in Crowdin older than a specified number of days.

• --days, -d <number> — Number of days to consider a branch stale (required)
• --delete-tasks, -dt — Whether to delete any associated tasks
• --project-id, -pi <id> — Required. Crowdin project ID

About --languages and --pre-translate-languages

• --languages / -l:
  Controls which languages are downloaded from Crowdin or targeted for operations.
  Example:

  mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --languages de,fr

  Only German and French translations will be processed.

• --pre-translate-languages / -ptl:
  Controls which languages will receive pre-translation when uploading or syncing.
  Example:

  mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --pre-translate --pre-translate-languages de,fr

  Only German and French will be pre-translated.

If not provided, both options default to all enabled languages in your Crowdin project.

Crowdin Branch Name

By default, @mollie/crowdin-cli uses the current Git branch name for Crowdin.
Override with --branch-name or -b:

mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --branch-name custom-branch

TypeScript Output

To write downloaded messages to TypeScript files, use the --typescript flag:

mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --typescript

Migrating from v3 to v4

Version 4 of @mollie/crowdin-cli introduces a simplified CLI and changes to configuration and commands. Here’s what you need to know to upgrade:

Key Changes

• Commands:
  Only three commands remain: sync, delete-branch, and delete-stale-branches.
  The previous upload, download, and collect commands are now handled by sync with flags.

• Environment Variables:

  • You no longer need to set CROWDIN_PROJECT_ID or CROWDIN_LANGUAGES in your .env file.
  • Always provide the project ID via the --project-id or -pi option.
  • Use the --languages/-l and --pre-translate-languages/-ptl flags for language selection.

• Scripts:
  Replace old scripts with the new unified sync command and flags:

  {
    "crowdin:sync": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id>",
    "crowdin:upload": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-download",
    "crowdin:download": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-upload",
    "crowdin:delete-branch": "mollie-crowdin delete-branch --project-id <your-project-id>",
    "crowdin:delete-stale-branches": "mollie-crowdin delete-stale-branches --project-id <your-project-id>"
  }

  • Use --skip-download to only upload messages.
  • Use --skip-upload to only download translations.

• Branch Name:
  The CLI now defaults to the current Git branch name.
  Override with --branch-name or -b.

• TypeScript Output:
  To write downloaded messages to TypeScript files, use the --typescript flag with sync.

Example Migration

Old v3 scripts:

{
  "crowdin:download": "mollie-crowdin download",
  "crowdin:upload": "mollie-crowdin upload './src/**/!(*.{d,test})*.ts*'",
  "crowdin:delete-branch": "mollie-crowdin delete-branch"
}

New v4 scripts:

{
  "crowdin:sync": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id>",
  "crowdin:upload": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-download",
  "crowdin:download": "mollie-crowdin sync './src/**/!(*.{d,test})*.ts*' --project-id <your-project-id> --skip-upload",
  "crowdin:delete-branch": "mollie-crowdin delete-branch --project-id <your-project-id>"
}

Old environment variables:

CROWDIN_PERSONAL_ACCESS_TOKEN=your-token
CROWDIN_PROJECT_ID=your-project-id
CROWDIN_LANGUAGES=nl,en-US,fr,fr-BE

New environment variables:

CROWDIN_PERSONAL_ACCESS_TOKEN=your-token

(Provide project ID and languages via CLI options.)

Development

Install dependencies and set up your environment:

nvm install