Locize CLI

Common errors

• locize: command not found

  cause The `locize-cli` package is not installed globally or its installation directory is not in your system's PATH.
  fix Install `locize-cli` globally using `npm install -g locize-cli`. Verify your npm global bin directory is in your system's PATH.

• Error: Invalid API Key / Error: Project not found

  cause The provided `--api-key` or `--project-id` is incorrect, missing, or does not have the necessary permissions for the operation.
  fix Double-check your API Key and Project ID for typos. Ensure the API Key has sufficient permissions for the requested action (e.g., read, write, admin access).

• Error: Cannot find module 'locize-cli'

  cause Attempting to use `require()` or `import` with `locize-cli` in a JavaScript/TypeScript file, treating it as a library.
  fix `locize-cli` is a command-line interface tool meant for shell execution, not programmatic import. Use `npm install -g locize-cli` and run `locize [command]` in your terminal.

Warnings

• gotcha Namespace names become filenames on disk. Using characters such as `< > : " / \ | ? *` in your namespace names can lead to file writing issues on various operating systems.
  Fix: Use only letters, numbers, hyphens ('-'), and underscores ('_') when naming your namespaces to ensure cross-platform compatibility.
• gotcha When specifying the translation version for commands like `download`, use `--ver` instead of `--version`. The `--version` flag is reserved for printing the CLI tool's own version number.
  Fix: Always use `--ver` followed by the desired version (e.g., `latest`) when referencing translation versions in your commands.
• gotcha When using the `sync` command, the CLI operates on published translations by default. If you intend to synchronize with unpublished translations, you must explicitly enable this.
  Fix: Ensure the desired version on locize is set to auto-publish, or include the `--unpublished true` option in your `sync` command to work with unpublished translations.
• breaking Versions of `locize-cli` 12.x and above require Node.js version 22 or higher to function correctly.
  Fix: Upgrade your Node.js environment to version 22 or higher. You can use a Node.js version manager like `nvm` to easily switch between versions.

Install

• npm install locize-cli npm
• yarn add locize-cli yarn
• pnpm add locize-cli pnpm

Imports

• locize-cli
  wrong:

  import { locize } from 'locize-cli'

  correct:

  npm install -g locize-cli

  This is a global command-line interface tool, not a library for programmatic import within JavaScript/TypeScript code. It is executed via the `locize` command in the terminal after global installation.

Quickstart

This quickstart provides JavaScript code that outputs common `locize-cli` commands for adding, removing, downloading, and synchronizing translation keys and files. It demonstrates how to interact with the locize platform from your terminal, using placeholder environment variables for API keys and project IDs.

// To run these commands, first install the CLI globally:
// npm install -g locize-cli

const API_KEY = process.env.LOCIZE_API_KEY ?? 'YOUR_LOCIZE_API_KEY'; // Replace or set LOCIZE_API_KEY env var
const PROJECT_ID = process.env.LOCIZE_PROJECT_ID ?? 'YOUR_LOCIZE_PROJECT_ID'; // Replace or set LOCIZE_PROJECT_ID env var

console.log('--- Locize CLI Quickstart ---\n');
console.log('To add/update a new translation key (e.g., in English, namespace 'namespace1'):');
console.log(`locize add --api-key ${API_KEY} --project-id ${PROJECT_ID} --language en namespace1 myNewKey "My new value"\n`);

console.log('To remove a translation key:');
console.log(`locize remove --api-key ${API_KEY} --project-id ${PROJECT_ID} --language en namespace1 myNewKey\n`);

console.log('To download current published files for a specific language and namespace to a local directory:');
console.log(`locize download --project-id ${PROJECT_ID} --ver latest --language en --namespace namespace1 --path ./backup\n`);

console.log('To synchronize local translation files with the locize platform (example path, adjust as needed):');
console.log(`locize sync --api-key ${API_KEY} --project-id ${PROJECT_ID} --path './src/locales/{{lng}}/{{ns}}.json' --language 'en' --pull-local-missing true --push-remote-missing true\n`);

console.log('Please ensure your API_KEY and PROJECT_ID are correctly set (preferably via environment variables) before running these commands in your shell/terminal.');