Lingo.dev Documentation

The Lingo compiler automatically transforms React components to inject translation calls at build time. The process follows this high-level flow:

1. File Filtering: Identifies .tsx and .jsx files (skipping node_modules).
2. Code Parsing: Converts source code into a Babel AST.
3. Component Detection: Identifies React components (Server or Client components).
4. Text Extraction: Finds translatable text nodes in JSX and generates unique hashes.
5. Code Transformation: Replaces text nodes with translation calls (e.g., t(hash, fallback)).
6. Code Generation: Converts the modified AST back into JavaScript code with source maps.
7. Metadata Management: Stores extraction data in an LMDB database.

The @lingo.dev/compiler package includes the following features:

• Advanced virtual module system: Provides better code splitting.
• Built-in development translation server: Facilitates real-time translation during development.
• Pluralization detection: Supports ICU MessageFormat.
• Improved metadata management: Enables better caching.
• Thread-safe concurrent build support: Optimized for modern build environments.

Lingo.dev provides several tools for localization engineering:

• Lingo React MCP: AI-assisted i18n configuration for React applications. Use the prompt Set up i18n with supported AI coding assistants.
• CLI Lingo: Localizes JSON, YAML, markdown, CSV, and PO files. Run via npx lingo.dev@latest run.
• GitHub Action Lingo: Enables continuous localization in your CI/CD pipeline using uses: lingodotdev/lingo.dev@main.
• Lingo React Compiler (Early Alpha): Provides compile-time localization for React without i18n wrappers or translation keys. Use the withLingo() plugin. Compatible with Next.js (App Router) and Vite + React.

The Lingo CLI allows you to translate multiple file formats including JSON, YAML, markdown, CSV, and PO. It uses a lock file to track translations, ensuring only new or modified content is processed. By default, it uses your translation engine from Lingo.dev, but you can also use your own LLM (OpenAI, Anthropic, Google, Mistral, OpenRouter, or Ollama).

npx lingo.dev@latest init
npx lingo.dev@latest run

Starting from version 0.130.0, the Lingo.dev GitHub Action supports GPG commit signing. This allows the action to sign commits using the -S flag.

To use this feature, you must:

1. Configure a GPG private key in your GitHub Secrets.
2. Use the crazy-max/ghaction-import-gpg action to import the key.
3. Set git_user_signingkey and git_commit_gpgsign to true in the GPG action.
4. Set gpg-sign: true in the lingodotdev/lingo.dev action configuration.

- uses: crazy-max/ghaction-import-gpg@v6
  with:
    gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
    git_user_signingkey: true
    git_commit_gpgsign: true

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    gpg-sign: true

The Lingo CLI allows you to localize JSON, YAML, markdown, CSV, and PO files in a single command. It uses a lock file to track previously localized content, ensuring only new or modified content is processed. By default, it uses your Lingo.dev localization engine, but you can also use your own LLM (OpenAI, Anthropic, Google, Mistral, OpenRouter, or Ollama).

npx lingo.dev@latest init
npx lingo.dev@latest run