locize-cli

Getting started with the locize-cli

Step 0: Install the cli

with npm (preferred globally)

npm install -g locize-cli

ℹ️ Since v12.5.1 the SheetJS xlsx library is bundled into the package (Apache-2.0, license included), so installing works with every package manager. Older releases pinned xlsx to the official SheetJS CDN tarball (the npm registry version is outdated and has known vulnerabilities), which pnpm 11 (ERR_PNPM_EXOTIC_SUBDEP) and npm 12 (EALLOWREMOTE) block by default — for locize-cli <= 12.5.0 on pnpm, set blockExoticSubdeps: false in your pnpm-workspace.yaml.

with Shell: (downloads released (linux or macos) binaries)

curl -fsSL https://raw.githubusercontent.com/locize/locize-cli/master/install.sh | sh

with PowerShell: (downloads released (windows) binaries)

iwr https://raw.githubusercontent.com/locize/locize-cli/master/install.ps1 -useb | iex

⚠️ Filename restrictions
The namespace you choose becomes your on-disk filename, so please avoid these characters:

<   (less than)
>   (greater than)
:   (colon)
"   (double quote)
/   (forward slash)
\   (backslash)
|   (vertical bar or pipe)
?   (question mark)
*   (asterisk)

These are sometimes illegal on various operating systems, so using them may lead to files not being written or being written incorrectly. If necessary, use only letters, numbers, hyphens ("-") and underscores ("_") in your namespace names.

Adding/Updating new keys

Step 1: execute

Add your api-key and your project-id and let's go...

locize add --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --language en namespace1 myNewKey "My new value"

Remove keys

Step 1: execute

Add your api-key and your project-id and let's go...

locize remove --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --language en namespace1 myNewKey

or

locize remove common title

or remove multiple keys at once (batched into one request per language):

locize remove common title subtitle description

Get keys

Step 1: execute

Add your project-id and let's go...

locize get --project-id my-project-id-93e1-442a-ab35-24331fa294ba --language en namespace1 myNewKey

or

locize get common title

Download current published files

The CLI will use the normal API endpoints to download the translations, so normal download charges etc. will occur.

Step 1: execute

Add your project-id and let's go...

locize download --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver latest --language en --namespace namespace1 --path ./backup

Make sure to use --ver and not --version (--version will print the CLI version).

or

locize download
locize download --cdn-type standard
locize download --cdn-type pro

or add a format like (json, nested, flat, xliff2, xliff21, xliff22, xliff12, xlf2, xlf21, xlf22, xlf12, android, yaml, yaml-rails, yaml-rails-ns, yaml-nested, yml, yml-rails, yml-nested, csv, xlsx, po, strings, resx, fluent, tmx, laravel, properties, xcstrings)

Special formats:

• use yaml-rails to have the language code in the resulting yaml as root object
• use yaml-rails-ns to have the namespace in the resulting yaml as first key scope
• xcstrings (Apple String Catalog): conversion happens at the file level, not at the in-string syntax level — i18next-style plural suffixes (key_one/key_other) stay separate entries (they are not merged into variations.plural) and interpolation placeholders like {{name}} are not rewritten to %@/%lld format specifiers. For a clean String Catalog export, the content should already use xcstrings-native plural variations and format specifiers.

locize download --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver latest --language en --namespace namespace1 --path ./backup --format android

GitHub Action

There's also a GitHub Action that handles the download in your CI/CD workflow.

Synchronize Locize with your repository (or any other local directory)

By using the sync command, you can keep your existing code setup and synchronize the translations with Locize. An example on how this could look like can be seen in this tutorial.

⚠️ Since the remote source are the published translations, make sure the desired version is set to auto publish mode. Alternatively use the --unpublished true argument (these requests count as private downloads: included from the Growth plan on, refused with a 403 on Free, Starter and Starter-Plus). ⚠️

The CLI will use the normal API endpoints, so normal modification and download charges etc. will occur.

If you need to change or remove multiple keys, please do NOT execute the sync command after each individual key change, but make the changes all together and then execute the sync command once.

Step 1: Go near to your translation files

cd my-awesome-project/locales

Make sure you have this type of tree structure: Each language should be a directory and each namespace should be a file

locales
├── en
│   ├── namespace1.extension
│   ├── namespace2.extension
│   ├── ...
├── de
│   ├── ...

the cli by will use the directory name as language and the filename (without extension as namespace name).

Step 3: execute

Add your api-key and your project-id and let's go...

locize sync --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba
locize sync --cdn-type standard --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba
locize sync --cdn-type pro --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

or add a format like (json, nested, flat, xliff2, xliff21, xliff22, xliff12, xlf2, xlf21, xlf22, xlf12, android, yaml, yaml-rails, yaml-rails-ns, yaml-nested, yml, yml-rails, yml-nested, csv, xlsx, po, strings, resx, fluent, tmx, laravel, properties, xcstrings)

Special formats:

• use yaml-rails to have the language code in the resulting yaml as root object
• use yaml-rails-ns to have the namespace in the resulting yaml as first key scope
• xcstrings (Apple String Catalog): conversion happens at the file level, not at the in-string syntax level — i18next-style plural suffixes (key_one/key_other) stay separate entries (they are not merged into variations.plural) and interpolation placeholders like {{name}} are not rewritten to %@/%lld format specifiers. For a clean String Catalog export, the content should already use xcstrings-native plural variations and format specifiers.

locize sync --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --format android

‼️ By default: The reference language in your local repository is the master ‼️

• if you have new keys in your local namespace it will add the missing one to Locize
• if you have new namespaces in your local language directory it will add the missing one to Locize
• if you have less keys (you have deleted some keys) in your local namespace it will remove them in Locize too
• all non reference languages will always be just locally replaced by what is published on Locize, unless the --skip-delete true argument is used
• if you change the values of existing keys in the reference language, it will not change them in Locize (to change the existing values you have to change it directly in Locize or use the --update-values true argument)
• if you update existing keys (with --update-values true) the automatic translation is not triggered, unless the --auto-translate true argument us used
• if you want to restrict the automatic translation to specific target languages only, you can use the --auto-translate-languages de,fr argument (together with --auto-translate true); if omitted, all languages are auto-translated
• if you want to take into account all languages instead of the reference language only while comparing the namespace content between local and remote, you can use the command argument --reference-language-only false
• if you want your target languages to arrive as review proposals instead of being written directly, you can use the command argument --review true (together with --reference-language-only false); the values only go live once someone accepts them in the editor, and it applies to target languages only, never to your reference language. Review proposals have to be enabled for those languages in your project settings
• if your target languages should go live right away but still get a second look, use --needs-review true (together with --reference-language-only false): every sent value is marked as needing review and shows up in the editor's review queue until someone confirms it. Target languages only; ignored together with --review true. See review workflow
• gettext files carry that mark as #, fuzzy: fuzzy entries in your .po files arrive marked as needing review (target languages), and a download with --unpublished true writes marked values back out as fuzzy (published files carry no marks)
• if you want to take into account the modification time while comparing the namespace content between local and remote, you can use the command argument --compare-modification-time true
• if you only want to sync the keys that changed on your current git branch (for example to auto-translate just a pull request's diff), use --changed-only true: it diffs your local reference-language files against the merge-base with the base branch (auto-detected via origin/HEAD, main, master, or set explicitly with --base <ref>) and restricts additions, value updates and auto-translation to those keys (deletions are skipped). Keys are scoped per namespace file, and if any plural variant of a key changed, all its plural forms are included (target languages often need more CLDR plural forms than the source). Requires git and a non-shallow checkout; on GitHub Actions use actions/checkout with fetch-depth: 0

locize sync --changed-only true --auto-translate true
locize sync --changed-only true --base develop

Step 4: verify

Navigate to your Locize project and check the results => www.locize.app

Push missing keys to Locize from your repository (or any other local directory)

This is useful, when i.e. using i18next-scanner, like described here. The save-missing command uses the missing API and the sync command uses the update API. So, if you want to save new keys (that does not exist in Locize), the save-missing command is the better choice. Doing so, you can then for example make use of the “created by missing API" filter in the Locize UI. Also, using this save-missing command does not generate extra modification costs.

But if you need to update existing keys, the sync command is the correct choice.

Step 1: Go near to your translation files

cd my-awesome-project/locales

Make sure you have this type of tree structure: Each language should be a directory and each namespace should be a file

locales
├── en
│   ├── namespace1.extension
│   ├── namespace2.extension
│   ├── ...
├── de
│   ├── ...

the cli by will use the directory name as language and the filename (without extension as namespace name).

Step 3: execute

Add your api-key and your project-id and let's go...

locize save-missing --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba
locize save-missing --cdn-type standard --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba
locize save-missing --cdn-type pro --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

or add a format like (json, nested, flat, xliff2, xliff21, xliff22, xliff12, xlf2, xlf21, xlf22, xlf12, android, yaml, yaml-rails, yaml-rails-ns, yaml-nested, yml, yml-rails, yml-nested, csv, xlsx, po, strings, resx, fluent, tmx, laravel, properties, xcstrings)

locize save-missing --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --format android

Step 4: verify

Navigate to your Locize project and check the results => www.locize.app

Copy version

It uses this API endpoint and it's the same behavior like overwriting via the UI.

Step 1: execute

Add your api-key (of target version) and your project-id and let's go...

# this will copy version latest to production
locize copy-version latest --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver production

Make sure to use --ver and not --version (--version will print the CLI version).

Publish version

Step 1: execute

Add your api-key and your project-id and let's go...

locize publish-version --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver production

Delete version

It uses this API endpoint.

Step 1: execute

Add your api-key and your project-id and let's go...

# this will remove version tmp-ver
locize remove-version tmp-ver --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

Delete namespace

Step 1: execute

Add your api-key and your project-id and let's go...

locize delete-namespace common --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver latest

Make sure to use --ver and not --version (--version will print the CLI version).

Migration of existing i18next files

We suggest to use the sync command instead of the migrate command. The migrate command should be used only once and only works with json files.

Step 1: Go near to your translation files

At the moment only i18next translation files (json) are supported

cd my-awesome-project/locales

Step 2: Decide if you want to migrate all languages or only one

If you have a directory structure like this:

locales
├── en
│   ├── namespace1
│   ├── namespace2
│   ├── ...
├── de
│   ├── ...

the cli by default will try to use the directory name as language.

If you have a directory structure like this:

locales
├── namespace1
├── namespace2
├── ...

you can use the --language option to define the language.

Step 3: execute

Add your api-key and your project-id and let's go...

locize migrate --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --path ./en --language en

Passing the argument --replace will empty the optionally existing namespace before saving the new translations. (default: false)

Step 4: verify

Navigate to your Locize project and check the results => www.locize.app

Format local files (i.e. in combination with download command)

Step 1: execute

Add your api-key and your project-id and let's go...

locize format path/to/dictionary --format android

Working with branches

Create a new branch

locize create-branch featureXYZ --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --ver latest

Sync or Download that branch

locize sync --branch featureXYZ --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

locize download --branch featureXYZ --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

Merge that branch

locize merge-branch featureXYZ --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba --delete true

Delete an unmerged branch

locize delete-branch featureXYZ --api-key my-api-key-d9de-4f55-9855-a9ef0ed44672 --project-id my-project-id-93e1-442a-ab35-24331fa294ba

Other information

You can define a config file in your home directory (or wherever you want (by specifying it in the command)) that contains defaults for your commands. i.e.

cat /Users/user/.locize

apiKey = my-api-key-d9de-4f55-9855-a9ef0ed44672
projectId = my-project-id-93e1-442a-ab35-24331fa294ba
language = en
version = latest
cdnType = standard

like this you can just work like this:

locize sync

or

locize add common title "the title of my cool app"

Additionally if these environment variables can be set:

• LOCIZE_PROJECTID or LOCIZE_PID
• LOCIZE_API_KEY or LOCIZE_KEY
• LOCIZE_VERSION or LOCIZE_VER
• LOCIZE_LANGUAGE or LOCIZE_LANG or LOCIZE_LNG
• LOCIZE_CDN_TYPE

they will also be considered with this priority:

1. argument as part of command (i.e. locize sync --project-id ...)
2. config value in .locize file (i.e. projectId = ...)
3. env variable (i.e. LOCIZE_PROJECTID) / or .env file

In case you have a .env file in the current working directory, it will be used to load environment variables from that .env file into process.env.