> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Crowdin adapter

> Configure Crowdin for native sync mode or Crowdin-compatible file mode.

## Two Crowdin workflows

Hyperlocalise now supports two different Crowdin integrations:

1. Native sync mode with `i18n.yml` plus `sync push` / `sync pull`
2. Crowdin-compatible file mode with `crowdin.yml` plus `hyperlocalise crowdin ...`

Use native sync mode when you want Hyperlocalise-managed entry sync.

Use file mode when you want a closer drop-in replacement for Crowdin CLI file workflows.

## Native sync mode

### Required config

```jsonc theme={null}
{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN"
    }
  }
}
```

### Crowdin Enterprise

Set `apiBaseURL` when your workspace uses Crowdin Enterprise instead of the default Crowdin Cloud API.

```jsonc theme={null}
{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN",
      "apiBaseURL": "https://example.api.crowdin.com"
    }
  }
}
```

### Optional config fields

* `apiBaseURL`: Override the Crowdin API base URL. Use this for Crowdin Enterprise.
* `sourceLanguage`
* `targetLanguages`
* `timeoutSeconds`

## Crowdin-compatible file mode

Use `crowdin.yml` or `crowdin.yaml`.

Example:

```yaml theme={null}
project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true

files:
  - source: /src/messages.json
    translation: /locales/%locale%/%original_file_name%
    export_only_approved: true
```

Supported `crowdin.yml` fields in v1:

* `project_id`
* `project_id_env`
* `api_token`
* `api_token_env`
* `base_url`
* `base_url_env`
* `base_path`
* `base_path_env`
* `branch`
* `preserve_hierarchy`
* `files[].source`
* `files[].translation`
* `files[].languages_mapping`
* `files[].excluded_target_languages`
* `files[].skip_untranslated_strings`
* `files[].skip_untranslated_files`
* `files[].export_only_approved`

Use the compatible CLI surface:

```bash theme={null}
hyperlocalise crowdin init
hyperlocalise crowdin config validate
hyperlocalise crowdin upload sources
hyperlocalise crowdin upload translations --language fr
hyperlocalise crowdin download sources
hyperlocalise crowdin download sources --file-id 101 --output /tmp/messages.json --force
hyperlocalise crowdin download translations --language fr --export-only-approved --skip-untranslated-strings
hyperlocalise crowdin download translations --language fr --merge-approved
hyperlocalise crowdin download translations --language fr --include-sources
```

`download sources` writes Crowdin source files into `files[].source` paths from `crowdin.yml`, or into a single `--output` file when you pass `--file-id`.

`download translations --merge-approved` merges approved JSON object keys into existing local translation files and preserves local keys omitted from Crowdin's approved export.
When Crowdin includes source-language fallback values in that export, Hyperlocalise skips values that still match the source JSON so previously translated local strings are preserved.

`download translations --include-sources` also downloads matching Crowdin source files into the configured `files[].source` paths before writing translations. Exact source paths can be created locally if missing; globbed source paths are limited to files matched by local glob expansion.

Use `download sources` when you only need source files. It avoids translation export work and is the preferred command for source-only automation.

Use root `branch:` in `crowdin.yml` or pass `--branch <name>` to upload and download files from a Crowdin branch. The flag overrides the config value for that command.

Validation fails closed on unsupported Crowdin fields or commands.

## Common issues

* token not found: export `CROWDIN_API_TOKEN`
* Enterprise API requests fail: verify `storage.config.apiBaseURL` points to your Enterprise API host and uses `https`
* project lookup failure: check project ID and account permissions
* partial updates: review conflict report with `--output json`
* file-mode validation errors: remove unsupported `crowdin.yml` fields or switch to native `i18n.yml` sync mode