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

​
Crowdin Enterprise

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

​
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:
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:
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