The Lingo.dev CLI translates apps and content by reading a single i18n.json configuration file, extracting translatable strings from your source files, and routing them through a localization engine or a raw LLM provider. It writes the translations back to disk and tracks what changed so the next run only processes the delta.
The five-step pipeline#
When you run npx lingo.dev@latest run, the CLI executes five steps in sequence:
Content discovery
The CLI scans your project for source and target files based on the bucket configurations in i18n.json. Each bucket defines a file format and a set of include/exclude patterns that tell the CLI where translatable content lives.
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}The [locale] placeholder resolves to your configured source and target locale codes at runtime.
Data cleaning
Not all content requires translation. The CLI filters out values that should remain unchanged across languages - numbers, booleans, ISO dates, UUIDs, URLs, and empty strings. This reduces the payload sent to the translation backend, lowering token consumption and processing time.
Delta calculation
The CLI computes SHA-256 fingerprints for every source string and compares them against the previous state stored in i18n.lock. Only new or modified content enters the translation pipeline. Unchanged strings are skipped entirely.
This incremental approach means a project with 10,000 keys where 12 changed only translates those 12 keys - not the full set.
Localization
The delta is sent to the configured translation backend. The CLI supports two modes:
| Mode | How it works |
|---|---|
| Lingo.dev Engine | Routes requests through your localization engine, applying brand voice, glossary, instructions, and model configuration automatically. |
| Raw LLM provider | Sends translation requests directly to OpenAI, Anthropic, Google, Mistral, OpenRouter, or Ollama with a custom prompt. |
The CLI retries failed requests with exponential backoff, saves partial progress, and processes multiple target languages concurrently.
Content injection
Translated strings are written back to disk at the exact positions where source content exists. The CLI preserves file structure and formatting to produce minimal, reviewable diffs. If Prettier is configured in your project, the output respects your formatting rules.
Output files#
A typical run produces two types of changes:
- Locale files - target language files updated with new and modified translations
i18n.lock- updated with content fingerprints for tracking state
Both should be committed to version control - either manually or automatically through CI/CD integration.