loco-cli

library0.2.4jsnpmunverified

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.

devops

npm install loco-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCO-CLI

loco-cli

devopsjavascriptv0.2.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'loco-cli';

✗ const { run } = require('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.

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();

loco --version

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=2.1.1

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'loco-cli'

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.

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')

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.

Upgrade

Version history

0.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/robrechtme/loco-cli ↗

packagehttps://www.npmjs.com/package/loco-cli ↗

homepagehttps://loco-cli.dev ↗