Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Usage

hyperlocalise crowdin init
hyperlocalise crowdin config validate [--config <path>] [--identity <path>]
hyperlocalise crowdin upload sources [--config <path>] [--identity <path>] [--branch <name>]
hyperlocalise crowdin upload translations [--config <path>] [--identity <path>] [--branch <name>] [--language <locale>]
hyperlocalise crowdin download [--config <path>] [--identity <path>] [--branch <name>] [--language <locale>] [--export-only-approved] [--skip-untranslated-strings] [--merge-approved] [--include-sources]

​
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
  • translation download/export back into your repo
  • optional source download back into files[].source with --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: 
hyperlocalise crowdin config validate
Upload source files: 
hyperlocalise crowdin upload sources
Upload only French translations: 
hyperlocalise crowdin upload translations --language fr
Upload sources to a Crowdin branch: 
hyperlocalise crowdin upload sources --branch feature/login
Download only approved French translations: 
hyperlocalise crowdin download --language fr --export-only-approved --skip-untranslated-strings
Download French translations and refresh the matching local source files: 
hyperlocalise crowdin download --language fr --include-sources
For exact files[].source paths, Hyperlocalise can write the source file even when it 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: 
files:
  - source: /src/messages.json
    translation: /locales/%locale%/%original_file_name%
    export_only_approved: true
    skip_untranslated_strings: true
Merge approved JSON strings into the existing local translation file without deleting local keys that are absent from the approved export: 
hyperlocalise crowdin download --language fr --merge-approved
--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.