<!-- LLM_VERSION_INFO
FORMAT: text/markdown
CONTENT_TYPE: article
ORIGINAL_URL: https://lingo.dev/en/docs/cli
ALTERNATE_VERSION: en/docs/cli/index.html (text/html)
EXTRACTION_DATE: 2026-04-18T22:16:28.349Z

This is the markdown version with text-only content (images converted to alt-text).
For rich formatting with images, request the HTML version at: en/docs/cli/index.html
-->

# Lingo.dev CLI

Max Prilutskiy·Updated about 1 month ago·2 min read

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](/content/en/docs/platform/engines/index.html) 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](/content/en/docs/cli#the-five-step-pipeline/index.html)

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](/content/en/docs/cli/supported-formats/index.html) in `i18n.json`. Each bucket defines a file format and a set of include/exclude patterns that tell the CLI where translatable content lives.

```json
{
  "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`](/content/en/docs/cli/lockfile/index.html). 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](/content/en/docs/platform/engines/index.html), applying [brand voice](/content/en/docs/platform/brand-voices/index.html), [glossary](/content/en/docs/platform/glossaries/index.html), [instructions](/content/en/docs/platform/instructions/index.html), and [model configuration](/content/en/docs/platform/llm-models/index.html) 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](/content/en/docs/cli#output-files/index.html)

A typical run produces two types of changes:

1. **Locale files** - target language files updated with new and modified translations
2. **`i18n.lock`** - updated with content fingerprints for tracking state

Both should be committed to version control - either manually or automatically through [CI/CD integration](/content/en/docs/cli/large-projects/index.html).

## [Next Steps](/content/en/docs/cli#next-steps/index.html)

[Setup

Install the CLI and generate your first translations](/content/en/docs/cli/setup/index.html) [i18n.json

Full configuration reference](/content/en/docs/cli/configuration/index.html) [Connect Your Engine

Route CLI translations through your localization engine](/content/en/docs/platform/connect-your-engine/index.html) [Supported Formats

JSON, YAML, Markdown, and 20+ file formats](/content/en/docs/cli/supported-formats/index.html)