Skip to main content

CLI Integration

Check locale files from your terminal or CI — and retranslate just the keys that fail. The fastest way to start.

View on GitHubView on npm

Features

One command, no config file
Any language your model speaks
Placeholder preservation and validation
Incremental mode — only new or changed keys are sent
Anthropic or OpenAI, or a custom adapter
Nested JSON in, identical shape out

Prerequisites

  • 1.Node.js 18 or newer
  • 2.An Anthropic or OpenAI API key of your own

Installation

npm install -D @shipi18n/cli

# or run it without installing
npx @shipi18n/cli --help

Configuration

Set your own LLM key in the environment. It is read at translation time and never written to disk or sent anywhere except your provider:

# .env — never commit this
ANTHROPIC_API_KEY=your-key-here

Use OPENAI_API_KEY instead if you pass --provider openai.

Usage

npx @shipi18n/cli translate locales/en.json -t es,fr,de

Examples

Translate one file into three languages

export ANTHROPIC_API_KEY=your-key-here
npx @shipi18n/cli translate locales/en.json -t es,fr,de

# writes locales/es.json, locales/fr.json, locales/de.json

Only translate what changed

# Existing translations are reused; only new or empty keys hit the model.
npx @shipi18n/cli translate locales/en.json -t es,fr --incremental

Use OpenAI instead

export OPENAI_API_KEY=your-key-here
npx @shipi18n/cli translate locales/en.json -t ja,ko -p openai

Best Practices

  • Run it in a pre-commit hook or a CI job so translations never drift from the source file.
  • Keep --incremental on: it is both cheaper and stable, since untouched strings are never re-rolled.
  • Commit the generated files. They are build inputs, and reviewing the diff catches bad output early.
  • Store the key in your CI secret store, never in the repo.

Troubleshooting

No API key found

Export ANTHROPIC_API_KEY (or OPENAI_API_KEY with -p openai) in the shell that runs the command. The CLI does not read .env files automatically — use dotenv or your shell.

A placeholder went missing in the output

The CLI warns when a placeholder present in the source is absent from a translation. Re-run that language; if it repeats, the string is usually ambiguous — add context to the key name.

Command not found

Use npx @shipi18n/cli, or add it as a devDependency and call it through an npm script.

Need help? Read the docs

View on GitHub