{"id":17286,"library":"locize-cli","title":"Locize CLI","description":"A command-line interface for interacting with the locize localization platform. Currently at version 12.1.1, the `locize-cli` streamlines localization workflows by allowing programmatic management of translation keys and files. It enables tasks such as adding, removing, and retrieving translation entries, as well as downloading published translations in a wide array of formats including JSON, XLIFF, Android, YAML, and more. The project maintains a regular release cadence, with minor patches and dependency updates often occurring on a weekly or bi-weekly basis. A key differentiator is its comprehensive `sync` command, which facilitates bidirectional synchronization between local translation files and the remote locize platform, enabling developers to maintain their existing code setup while keeping translations updated. It also offers a dedicated GitHub Action for seamless integration into CI/CD pipelines, making it an essential tool for automating localization processes for projects utilizing locize. This CLI is primarily used globally and does not provide an API for programmatic JavaScript imports, focusing instead on shell-based execution for routine localization tasks.","status":"active","version":"12.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/locize/locize-cli","tags":["javascript","cli","locize"],"install":[{"cmd":"npm install locize-cli","lang":"bash","label":"npm"},{"cmd":"yarn add locize-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add locize-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { locize } from 'locize-cli'","symbol":"locize-cli","correct":"npm install -g locize-cli"}],"quickstart":{"code":"// To run these commands, first install the CLI globally:\n// npm install -g locize-cli\n\nconst API_KEY = process.env.LOCIZE_API_KEY ?? 'YOUR_LOCIZE_API_KEY'; // Replace or set LOCIZE_API_KEY env var\nconst PROJECT_ID = process.env.LOCIZE_PROJECT_ID ?? 'YOUR_LOCIZE_PROJECT_ID'; // Replace or set LOCIZE_PROJECT_ID env var\n\nconsole.log('--- Locize CLI Quickstart ---\\n');\nconsole.log('To add/update a new translation key (e.g., in English, namespace 'namespace1'):');\nconsole.log(`locize add --api-key ${API_KEY} --project-id ${PROJECT_ID} --language en namespace1 myNewKey \"My new value\"\\n`);\n\nconsole.log('To remove a translation key:');\nconsole.log(`locize remove --api-key ${API_KEY} --project-id ${PROJECT_ID} --language en namespace1 myNewKey\\n`);\n\nconsole.log('To download current published files for a specific language and namespace to a local directory:');\nconsole.log(`locize download --project-id ${PROJECT_ID} --ver latest --language en --namespace namespace1 --path ./backup\\n`);\n\nconsole.log('To synchronize local translation files with the locize platform (example path, adjust as needed):');\nconsole.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`);\n\nconsole.log('Please ensure your API_KEY and PROJECT_ID are correctly set (preferably via environment variables) before running these commands in your shell/terminal.');","lang":"javascript","description":"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."},"warnings":[{"fix":"Use only letters, numbers, hyphens ('-'), and underscores ('_') when naming your namespaces to ensure cross-platform compatibility.","message":"Namespace names become filenames on disk. Using characters such as `< > : \" / \\ | ? *` in your namespace names can lead to file writing issues on various operating systems.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `--ver` followed by the desired version (e.g., `latest`) when referencing translation versions in your commands.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Versions of `locize-cli` 12.x and above require Node.js version 22 or higher to function correctly.","severity":"breaking","affected_versions":">=12.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `locize-cli` globally using `npm install -g locize-cli`. Verify your npm global bin directory is in your system's PATH.","cause":"The `locize-cli` package is not installed globally or its installation directory is not in your system's PATH.","error":"locize: command not found"},{"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).","cause":"The provided `--api-key` or `--project-id` is incorrect, missing, or does not have the necessary permissions for the operation.","error":"Error: Invalid API Key / Error: Project not found"},{"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.","cause":"Attempting to use `require()` or `import` with `locize-cli` in a JavaScript/TypeScript file, treating it as a library.","error":"Error: Cannot find module 'locize-cli'"}],"ecosystem":"npm","meta_description":null}