{"id":17448,"library":"loco-cli","title":"Loco CLI","description":"Loco CLI is a command-line interface tool designed to automate the synchronization of project translations with the Loco localization platform (localise.biz). It facilitates both pulling translations from Loco into your local project and pushing local changes back to Loco. The current stable version is 3.4.0, with a fairly active release cadence, frequently adding new features, improving types, and updating dependencies as seen in recent changelogs. A key differentiator is its focus as a Node.js-based solution, offering flexibility in configuration via `package.json` or various `.locorc` files, supporting both JSON and YAML formats, and now providing a dedicated documentation website. It aims to streamline the localization workflow for developers using JavaScript/TypeScript projects.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/robrechtme/loco-cli","tags":["javascript","cli","cli-app","loco","localize","typescript"],"install":[{"cmd":"npm install loco-cli","lang":"bash","label":"npm"},{"cmd":"yarn add loco-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add loco-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, internal functions like `run` might be exposed for programmatic execution. The package ships as an ES module since v3, so CommonJS `require` is incorrect. Direct programmatic usage is less common than command-line execution.","wrong":"const { run } = require('loco-cli');","symbol":"run","correct":"import { run } from 'loco-cli';"},{"note":"Imports for type definitions are common, especially when working with configuration files like `.locorc` or `loco.config.js` for type-safe setup. The package ships TypeScript types.","symbol":"LocoConfig","correct":"import type { LocoConfig } from 'loco-cli';"},{"note":"Similar to `LocoConfig`, type imports for command-specific options can be useful for extending or programmatically interacting with specific commands and ensuring type safety.","symbol":"LocoCommandOptions","correct":"import type { LocoCommandOptions } from 'loco-cli';"}],"quickstart":{"code":"import { run } from 'loco-cli';\nimport path from 'node:path';\n\nasync function syncTranslations() {\n  console.log('Starting translation sync...');\n  try {\n    // Example: Programmatically run the 'pull' command\n    // This assumes `run` function can accept arguments programmatically.\n    // In typical usage, you'd use 'npx loco-cli pull' from the terminal.\n    await run(['pull', '--config', path.resolve(process.cwd(), '.locorc.js')], { \n      cwd: process.cwd(),\n      // Pass environment variables or specific options needed by the CLI\n      env: { LOCO_API_KEY: process.env.LOCO_API_KEY ?? '', ...process.env }\n    });\n    console.log('Translations pulled successfully!');\n\n    // Example: Programmatically run the 'push' command with a specific tag\n    await run(['push', '--tag', 'web-app', '--yes'], { \n      cwd: process.cwd(),\n      env: { LOCO_API_KEY: process.env.LOCO_API_KEY ?? '', ...process.env }\n    });\n    console.log('Translations pushed successfully!');\n\n  } catch (error) {\n    console.error('Error during translation sync:', error);\n    process.exit(1);\n  }\n}\n\nsyncTranslations();","lang":"typescript","description":"Demonstrates programmatic execution of `loco-cli` commands ('pull' and 'push') within a TypeScript environment, including configuration loading and API key handling."},"warnings":[{"fix":"Upgrade your Node.js environment to version 14 or higher (Node.js 20+ is recommended for latest versions as per v3.1.0 changelog).","message":"Version 3.0.0 dropped support for Node.js 12 and upgraded various internal dependencies. Projects running on Node.js 12 will need to upgrade their Node.js runtime to continue using `loco-cli` v3.x.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate your configuration to a `.locorc` file (JSON, YAML, or JS module) for better maintainability and full feature access. Refer to the official documentation for examples.","message":"The configuration system was migrated to `cosmiconfig` in v2.1.1, introducing support for multiple configuration file formats (e.g., `.locorc`, `.locorc.json`, `loco.config.js`). While older direct CLI arguments might still work, using a dedicated configuration file is the recommended and most flexible approach.","severity":"gotcha","affected_versions":">=2.1.1"},{"fix":"Ensure `LOCO_API_KEY` and any other required environment variables are correctly set in your shell or CI/CD pipeline before running `loco-cli` commands.","message":"As a CLI tool, `loco-cli` heavily relies on environment variables (e.g., `LOCO_API_KEY`) for authentication. Forgetting to set these, or setting them incorrectly, is a common cause of operation failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install loco-cli` or `yarn add loco-cli` in your project, or ensure `npx loco-cli` is used for one-off commands if not globally installed.","cause":"The `loco-cli` package is not installed or not resolvable in the current project context.","error":"Error: Cannot find module 'loco-cli'"},{"fix":"Set the `LOCO_API_KEY` environment variable in your terminal session (e.g., `export LOCO_API_KEY='your_key_here'`) or in your CI/CD configuration.","cause":"The required `LOCO_API_KEY` environment variable, essential for authenticating with the Loco API, has not been set.","error":"Error: Loco API key not found. Please set the LOCO_API_KEY environment variable."},{"fix":"Review the package's `index.d.ts` file or documentation for available programmatic exports. For typical usage, invoke `loco-cli` via `npx` or directly from the command line.","cause":"This error can occur if you are trying to programmatically access a non-existent or incorrectly imported function from the `loco-cli` package, or if the internal API has changed.","error":"TypeError: Cannot read properties of undefined (reading 'pull')"}],"ecosystem":"npm","meta_description":null}