Skip to main content

​
Usage

​
What this command family does

These commands operate on crowdin.yml or crowdin.yaml directly. They are separate from Hyperlocalise native i18n.yml and sync push / sync pull workflows. Use them when you want Crowdin-compatible file mode:
  • source-file upload from files[].source
  • translation upload from files[].translation
  • source download into files[].source or a single output file
  • translation download/export back into your repo
  • optional source download alongside translations with download translations --include-sources
  • branch-scoped upload and download with root branch: or --branch
  • strict YAML decoding: only keys Crowdin documents and hl recognizes may appear in crowdin.yml (unknown keys still error)

​
Supported config fields

These drive Hyperlocalise Crowdin file mode:
  • 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

​
Crowdin CLI compatibility (parsed, not applied)

The decoder also accepts several Crowdin-documented keys so you can reuse a standard crowdin.yml without stripping metadata. Hyperlocalise does not implement behavior for these yet; they are ignored after parse:
  • Root: export_languages, pull_request_title, pull_request_labels, commit_message, append_commit_message, pull_request_assignees, pull_request_reviewers
  • Per file: type, dest, update_option, export_pattern, translate_content, translate_attributes, content_segmentation, translatable_elements, ignore, translation_replace, first_line_contains_header, scheme, custom_segmentation, escape_quotes, escape_special_characters, labels

​
Unsupported features

YAML keys not listed above still cause a decode error (KnownFields). This v1 file-mode implementation does not support:
  • TM, glossary, task, screenshot, comment, distribution, or app commands
  • permissive “warn and ignore” compatibility mode
  • interactive Crowdin project bootstrap

​
Examples

Validate config:
Upload source files:
Upload only French translations:
Upload sources to a Crowdin branch:
Download source files from crowdin.yml into their configured files[].source paths:
Download one Crowdin source file by file ID:
When you pass --file-id, Hyperlocalise downloads that file directly from Crowdin. Use --output to write a file, or omit it to print the source content to stdout. Credentials still come from crowdin.yml, .crowdin.yml, or the usual CROWDIN_PROJECT_ID and CROWDIN_PERSONAL_TOKEN environment variables. Limit a config-based source download to one or more configured paths:
Download only approved French translations:
Download French translations and refresh the matching local source files:
With download translations --include-sources, exact files[].source paths can be written even when the file is missing locally. For globbed source paths, local glob expansion still determines which configured files are processed. Or configure the export behavior in crowdin.yml:
Merge approved JSON strings into the existing local translation file without deleting local keys that are absent from the approved export:
download translations --merge-approved currently supports JSON object translation files. It forces an approved-only sparse export for the request, then overwrites only keys present in the approved Crowdin payload. Downloaded values that still match the source JSON are treated as Crowdin source-language fallbacks and are not merged over existing local translations.