Loco CLI

Common errors

• Error: Cannot find module 'loco-cli'

  cause The `loco-cli` package is not installed or not resolvable in the current project context.
  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.

• Error: Loco API key not found. Please set the LOCO_API_KEY environment variable.

  cause The required `LOCO_API_KEY` environment variable, essential for authenticating with the Loco API, has not been set.
  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.

• TypeError: Cannot read properties of undefined (reading 'pull')

  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.
  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.

Warnings

• breaking 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.
  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).
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

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

Imports

• run
  wrong:

  const { run } = require('loco-cli');

  correct:

  import { run } from 'loco-cli';

  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.
• LocoConfig

  import type { LocoConfig } from 'loco-cli';

  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.
• LocoCommandOptions

  import type { LocoCommandOptions } from 'loco-cli';

  Similar to `LocoConfig`, type imports for command-specific options can be useful for extending or programmatically interacting with specific commands and ensuring type safety.

Quickstart

Demonstrates programmatic execution of `loco-cli` commands ('pull' and 'push') within a TypeScript environment, including configuration loading and API key handling.

import { run } from 'loco-cli';
import path from 'node:path';

async function syncTranslations() {
  console.log('Starting translation sync...');
  try {
    // Example: Programmatically run the 'pull' command
    // This assumes `run` function can accept arguments programmatically.
    // In typical usage, you'd use 'npx loco-cli pull' from the terminal.
    await run(['pull', '--config', path.resolve(process.cwd(), '.locorc.js')], { 
      cwd: process.cwd(),
      // Pass environment variables or specific options needed by the CLI
      env: { LOCO_API_KEY: process.env.LOCO_API_KEY ?? '', ...process.env }
    });
    console.log('Translations pulled successfully!');

    // Example: Programmatically run the 'push' command with a specific tag
    await run(['push', '--tag', 'web-app', '--yes'], { 
      cwd: process.cwd(),
      env: { LOCO_API_KEY: process.env.LOCO_API_KEY ?? '', ...process.env }
    });
    console.log('Translations pushed successfully!');

  } catch (error) {
    console.error('Error during translation sync:', error);
    process.exit(1);
  }
}

syncTranslations();