How it works

Lingo.dev CLI encapsulates complex localization processing workflow behind an elegant command-line interface.

When you run npx lingo.dev@latest i18n, the CLI reads the standard i18n.json configuration file and performs the following 5 steps:

1. Content discovery

Lingo.dev CLI treats your project as the source of truth. It recursively scans the project for translation source and target files based on your bucket configurations, reading them into memory for processing.

The discovery phase respects:

  • Include patterns like locales/[locale].json
  • Exclude patterns for files you want to skip
  • Multiple bucket configurations for different file types

2. Data cleaning

Not all content requires translation. Production applications contain numbers, booleans, dates, UUIDs, and code snippets that typically remain unchanged across languages.

Lingo.dev CLI intelligently filters out:

  • Numeric values like 42 or 3.14
  • Boolean values (true/false)
  • ISO dates and timestamps
  • UUIDs and similar identifiers
  • Code blocks and technical snippets

This filtering reduces LLM inference costs and improves processing speed by focusing only on translatable content.

3. Delta calculation

Content that hasn't changed shouldn't be re-translated. Lingo.dev CLI implements a sophisticated versioning system that:

  • Creates content fingerprints using SHA-256 hashing
  • Compares current content against the previous state stored in i18n.lock
  • Identifies new, modified, and deleted translation keys
  • Sends only the delta to the translation engine

This incremental approach means you only pay for what's new or changed, not your entire content library on every run.

Learn more: i18n.lock Lockfile

4. Localization

Localization must be reliable, even with flaky internet connections or LLM provider outages. At this step, Lingo.dev CLI takes the delta and sends it to your configured translation backend.

The CLI implements:

  • Exponential backoff retry strategy for network failures
  • Automatic error recovery and partial progress saving
  • Support for both raw LLM APIs (OpenAI, Anthropic) and Lingo.dev Engine
  • Concurrent processing for multiple target languages

Each translation request includes contextual information to ensure consistency and quality across your entire project.

5. Content injection

To maintain clean, reviewable changesets, Lingo.dev CLI injects translations at the exact positions where source content exists. This approach:

  • Preserves file structure and formatting
  • Avoids unnecessary git conflicts
  • Creates minimal, focused diffs
  • Respects your existing Prettier configuration if present

The result is localized files that look like they were crafted by hand, ready for code review and deployment.

The complete workflow

These five steps typically produce two types of changes:

  1. Localization files — Updated with new and modified translations
  2. i18n.lock file — Updated with content fingerprints for tracking state

Both should be committed to your repository, either manually or automatically through CI/CD integrations.

This architecture ensures Lingo.dev CLI scales efficiently from a single developer translating a few strings to teams managing millions of words across dozens of languages.

Next steps

Now that you understand how Lingo.dev CLI works internally, you can:

  • Join our community: Discord — Connect with other developers using Lingo.dev CLI, share feedback, and get help with your localization challenges;
  • Contribute to the project: Open issues — Lingo.dev CLI is open source and welcomes contributions. Browse open issues, suggest features, or submit pull requests to help improve the tool for everyone.