Crowdin CLI workflows with Hyperlocalise

Use hyperlocalise crowdin to upload source files, retrieve approved translations, and manage supported Crowdin resources from your terminal. Crowdin workflows live alongside local AI translation, checks, and other TMS commands in the all-in-one localization CLI.

Start with a Crowdin upload and download

Install Hyperlocalise. Use an existing Crowdin project with a French target language, a source file at locales/en.json, and a personal token with access to the project. Set CROWDIN_PERSONAL_TOKEN in your shell or CI secret manager. Replace the project ID in crowdin.yml:

project_id: "your-project-id"
api_token_env: CROWDIN_PERSONAL_TOKEN
files:
    - source: /locales/en.json
      translation: /locales/%two_letters_code%.json

hyperlocalise crowdin config validate
hyperlocalise crowdin upload sources
# Translate and approve the French strings in Crowdin before downloading.
hyperlocalise crowdin download translations --language fr --export-only-approved

The upload sends the configured source file to Crowdin. The download writes the French export to locales/fr.json. Review the file before committing it. For partial approved exports, use the JSON merge guide. To automate this workflow, see Crowdin in GitHub Actions.

Hyperlocalise vs the official Crowdin CLI

Hyperlocalise is a Crowdin CLI alternative for the file and resource operations listed on this page. It reuses supported Crowdin configuration fields, while adding local AI translation and other TMS command families in the same executable.

Task	Official Crowdin CLI workflow	Hyperlocalise
Upload configured sources	`crowdin upload sources`	`hyperlocalise crowdin upload sources`
Download translations	`crowdin download translations`	`hyperlocalise crowdin download translations`
Inspect progress	`crowdin status`	`hyperlocalise crowdin status`
Reuse configuration	`crowdin.yml`	Supported fields apply; some are accepted but ignored
Manage screenshots, tasks, or distributions	Use the official tool for its supported operations	Not available in this command family

Compare your script with the supported fields and gaps below before switching. See the official Crowdin CLI documentation for the vendor’s full command surface.

Command reference

hyperlocalise crowdin init
hyperlocalise crowdin config validate [--config <path>] [--identity <path>]
hyperlocalise crowdin config sources [--config <path>] [--identity <path>] [--output text|json]
hyperlocalise crowdin config translations [--config <path>] [--identity <path>] [--language <id>] [--output text|json]
hyperlocalise crowdin status [--config <path>] [--identity <path>] [--branch <name>] [--language <id>] [--output text|json] [--fail-if-incomplete]
hyperlocalise crowdin branch list [--config <path>] [--identity <path>] [--output text|json]
hyperlocalise crowdin branch add --name <name> [--config <path>] [--identity <path>]
hyperlocalise crowdin file list [--config <path>] [--identity <path>] [--branch <name>] [--output text|json]
hyperlocalise crowdin file upload <file> --dest <crowdin-path> [--config <path>] [--identity <path>] [--branch <name>]
hyperlocalise crowdin file download <crowdin-path> [--dest <path>] [--language <id>] [--config <path>] [--identity <path>] [--branch <name>] [--force]
hyperlocalise crowdin file delete <crowdin-path> [--config <path>] [--identity <path>] [--branch <name>]
hyperlocalise crowdin string list [--config <path>] [--identity <path>] [--branch <name>] [--file <crowdin-path>] [--filter <text>] [--output text|json]
hyperlocalise crowdin language list [--config <path>] [--identity <path>] [--all] [--output text|json]
hyperlocalise crowdin auto-translate --language <id> [--file <crowdin-path> | --branch <name> | --directory-id <id>] [--method tm] [--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 sources [--config <path>] [--identity <path>] [--branch <name>] [--file-id <id>] [--source <path>] [--output <path>] [--force]
hyperlocalise crowdin download translations [--config <path>] [--identity <path>] [--branch <name>] [--language <locale>] [--export-only-approved] [--skip-untranslated-strings] [--merge-approved] [--include-sources]
hyperlocalise crowdin glossary list [--config <path>] [--identity <path>] [--output text|json]
hyperlocalise crowdin glossary download --glossary-id <id> [--language <id>] [--output <path>]
hyperlocalise crowdin glossary upload --glossary-id <id> --input <file.tbx>
hyperlocalise crowdin tm list [--config <path>] [--identity <path>] [--output text|json]
hyperlocalise crowdin tm download --tm-id <id> --source-language <id> --target-language <id> [--format csv|tmx]
hyperlocalise crowdin tm upload --tm-id <id> --input <file.tmx>

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 commands with root branch: or --branch (the flag overrides YAML for that command)
translation and approval progress with status
branch list/add, file list, language list, and configured source/translation listing
path-based file upload / file download / file delete (distinct from batch crowdin.yml upload/download)
source string listing with string list
TM auto-translate (auto-translate, alias pre-translate)
glossary and translation-memory list, download, and upload
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:

screenshot, comment, task, distribution, or app commands
glossary CSV/TBX scheme mapping (upload accepts Crowdin-native TBX only)
TM CSV import (upload accepts Crowdin-native TMX only)
CroQL, labels, and directory filters on string list
MT/AI auto-translate (--method mt / ai)
niche file upload flags (--xliff, parser version, cleanup mode)
permissive “warn and ignore” compatibility mode
interactive Crowdin project bootstrap

Examples

Validate config:

hyperlocalise crowdin config validate

List source and translation paths from crowdin.yml:

hyperlocalise crowdin config sources
hyperlocalise crowdin config translations --language fr

Show translation and approval progress:

hyperlocalise crowdin status --language es --output json

List branches, files, and languages:

hyperlocalise crowdin branch list
hyperlocalise crowdin file list --branch feature/login
hyperlocalise crowdin language list

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 source files from crowdin.yml into their configured files[].source paths:

hyperlocalise crowdin download sources

Download one Crowdin source file by file ID:

hyperlocalise crowdin download sources --file-id 101 --output /tmp/messages.json --force

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:

hyperlocalise crowdin download sources --source /src/messages.json

Download only approved French translations:

hyperlocalise crowdin download translations --language fr --export-only-approved --skip-untranslated-strings

Download French translations and refresh the matching local source files:

hyperlocalise crowdin download translations --language fr --include-sources

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:

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 translations --language fr --merge-approved

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. List glossaries and translation memories, then import Crowdin-native files:

hyperlocalise crowdin glossary list
hyperlocalise crowdin glossary upload --glossary-id 77 --input terms.tbx
hyperlocalise crowdin tm list
hyperlocalise crowdin tm upload --tm-id 4 --input memory.tmx

glossary upload accepts TBX only. The CSV from glossary download is a Hyperlocalise export format and is not import-compatible. tm upload accepts TMX only. The CSV from tm download is not import-compatible. Re-importing TMX produced by tm download --format tmx is best-effort. List source strings (not translated values):

hyperlocalise crowdin string list --file messages.json --filter hello

Upload, download, or delete one file by Crowdin project path. Paths are branch-relative; do not prefix them with the branch name.

hyperlocalise crowdin file upload ./src/messages.json --dest /messages.json
hyperlocalise crowdin file download /messages.json --dest /tmp/messages.json --force
hyperlocalise crowdin file download /messages.json --language fr --dest /tmp/messages.fr.json --force
hyperlocalise crowdin file delete /messages.json --branch feature/login

file download without --language downloads the source file. Pass --language to build and download that file’s translations. For a numeric file ID, keep using download sources --file-id. Pre-translate with translation memory (v1 is TM only). pre-translate is an alias of auto-translate. Provide exactly one of --file, --branch, or --directory-id. --branch may accompany --file to resolve a branch-relative path. Root branch: in crowdin.yml also scopes --file and branch-only runs; --directory-id ignores that config value unless you also pass --branch.

hyperlocalise crowdin auto-translate --language fr --file messages.json
hyperlocalise crowdin pre-translate --language fr --branch feature/login

​Start with a Crowdin upload and download

​Hyperlocalise vs the official Crowdin CLI

​Command reference

​What this command family does

​Supported config fields

​Crowdin CLI compatibility (parsed, not applied)

​Unsupported features

​Examples

​Related workflows