npm package: @mollie/crowdin-cli
Description: A helper tool to sync translation messages with [Crowdin](https://crowdin.com/), using [`@formatjs/cli`](https://formatjs.io/docs/tooling/cli/) for message extraction.
Latest version: 4.0.2

# Crowdin CLI

A helper tool to sync translation messages with [Crowdin](https://crowdin.com/), using [`@formatjs/cli`](https://formatjs.io/docs/tooling/cli/) for message extraction.

## Installation

```shell
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:

```shell
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):

```json
{
  "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:

  ```shell
  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:
  ```shell
  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`:

```shell
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:

```shell
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:

  ```json
  {
    "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:**

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

**New v4 scripts:**

```json
{
  "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:**

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

**New environment variables:**

```shell
CROWDIN_PERSONAL_ACCESS_TOKEN=your-token
```

(Provide project ID and languages via CLI options.)

---

## Development

Install dependencies and set up your environment:

```shell
nvm install
```