Skip to main content
Use hyperlocalise lokalise to upload locale files, wait for queued imports, and download translations from a Lokalise project. Keep these operations alongside local AI translation and other TMS workflows in the all-in-one localization CLI.

​
Start with a Lokalise upload and download

Install Hyperlocalise, set LOKALISE_API_TOKEN in your shell or CI secret manager, and use a project with English and French locales. Create locales/en.json with your source strings. Replace your-project-id with the ID from Lokalise:
Use the locale codes returned by locales list. The upload waits for processing; it does not wait for human translation. The download writes the exported French file. Review it before committing; use --force only when you intend to replace an existing output file. For existing translated files, follow upload translations and wait for processing.

​
Hyperlocalise vs the official Lokalise CLI

Hyperlocalise is a Lokalise CLI alternative for the documented file workflows. It uses upload sources and download translations instead of the official lokalise2 file upload and file download syntax. You must adapt flags and credentials when moving scripts. Prefix commands in the last column with hyperlocalise. Existing Lokalise CLI config files are not read. See the official lokalise2 documentation when your workflow needs broader API coverage.

​
Command reference

These commands are flag-only. Hyperlocalise does not read a Lokalise YAML config in this version. You can pass --config to reuse projectID and token settings from an i18n.yml storage block.

​
What this command family does

These commands talk to the Lokalise API v2 file, language, queued-process, and glossary endpoints. They are separate from Hyperlocalise native i18n.yml and sync push / sync pull workflows. Use shared TMS sync when you want Hyperlocalise-managed entry sync through the Lokalise adapter. Use this surface when you want flag-driven file upload and download against a Lokalise project. Use them for:
  • listing project locales (locales list; lokalise2 language list)
  • listing project files (files list; lokalise2 file list)
  • source-file upload (upload sources)
  • import of a pre-translated locale file (upload translations)
  • source download (download sources)
  • translation download (download translations)
  • glossary download (Hyperlocalise-shaped CSV)
Official lokalise2 uses file upload / file download with --lang-iso. Hyperlocalise keeps the same command family shape as Crowdin, Phrase, and Smartling (upload sources, download translations).

​
Credentials

Hyperlocalise reads --token-env (default LOKALISE_API_TOKEN). Do not put the API token in i18n.yml. Point apiTokenEnv at an environment variable instead.

​
Command notes

locales list prints id, iso, and name from Lokalise project languages. iso is the value to pass as --source-locale or --target-locale. Lokalise has no default-locale field on this API. --output is text or json, not a file path. Empty projects print nothing in text mode and [] with --output json. Both exit 0. files list prints id, filename, and keys. Keys with no file association appear as __unassigned__. --filter-filename is Lokalise’s substring filter, not a glob. --output is text or json. upload sources requires --project-id (or projectID in --config), --source-locale (or sourceLanguage in --config), and at least one --file. --dry-run checks files and flags and does not need a token. upload translations requires --target-locale on every run. It does not take the locale from sourceLanguage or targetLanguages in --config. Config may still supply the project id and token. The locale comes from the flag, not the filename: uploading en.json as French uses --target-locale fr. --replace-modified maps to Lokalise replace_modified. Off (the default) preserves translations Lokalise treats as modified. On replaces those modified translations from the uploaded file. It is not a guarantee that every existing key stays unchanged. Dry-run and the success line print modified_translations=preserved or modified_translations=replaced. Without --poll, success means the import is queued. The command prints a process id and stops. --poll waits until the queued process reaches finished (lokalise2 --poll). --poll-timeout defaults to 30s, matching lokalise2. CI should pass a longer duration such as --poll-timeout 10m. --poll does not mean translations were kept. --dry-run does not poll. --poll-timeout without --poll is ignored. This is not Phrase --wait. Lokalise matches files by name. Use the same filename as the source file when you can. Language codes in the name (en.json / fr.json) are usually treated as one file. A totally different name can create a second file. --file can repeat for several files in that one locale. Use a separate invocation for each target locale. --poll waits for each file in order. download translations can take more than one --target-locale. Use %locale% in --output when you download more than one locale to files. glossary download writes CSV to stdout unless you pass --output. That --output is a file path, unlike list --output text|json.

​
Crowdin and lokalise2 gap inventory

​
Examples

List locales, then upload a source file and wait for the import:
Upload a French translation that reuses the source filename:
Download French translations: