Skip to main content

​
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

{
  "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. 
{
  "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: 
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: 
hyperlocalise crowdin init
hyperlocalise crowdin config validate
hyperlocalise crowdin upload sources
hyperlocalise crowdin upload translations --language fr
hyperlocalise crowdin download --language fr --export-only-approved --skip-untranslated-strings
hyperlocalise crowdin download --language fr --merge-approved
hyperlocalise crowdin download --language fr --include-sources
--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. --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 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