Lingo.dev Compiler

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

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

Lingo.dev Compiler is a free, open-source build-time translation system for React applications. It detects translatable text in your JSX, generates AI-powered translations with full component context, and embeds them in per-locale bundles during the build process. Your source code stays unchanged - no manual translation key files to maintain, no separate dictionary loading at runtime.

See it in action: live demo on X

Before and after

tsxCopy

// Your code - unchanged
export function Welcome() {
  return <h1>Welcome to our app</h1>;
}
// Renders "Bienvenido a nuestra aplicacion" in Spanish

No code changes needed. Translations are determined at compile time, creating optimized per-locale bundles.

How it differs from traditional i18n libraries

Traditional i18n libraries Lingo.dev Compiler
Translation management Manual - you create and maintain key files Automatic - the compiler extracts translatable strings from JSX
Code changes required Wrap every string in t() calls None - write normal JSX
How translations load Separate dictionary files loaded at runtime Embedded in per-locale bundles at build time
Translation source Manual or external TMS AI-generated with full component context
Dictionary fetching Runtime fetch or import of translation files No separate fetch - translations are part of the bundle

The build pipeline

  1. AST analysis

    The compiler parses your React code into an Abstract Syntax Tree using Babel. It identifies translatable content: text nodes, string attributes (alt, aria-label, placeholder), and template expressions.

  2. Content extraction

    Each translatable string gets a stable hash-based identifier. The compiler preserves component context, rich text structure (nested <strong>, <em>), and interpolation placeholders. Metadata is stored in .lingo/metadata.json.

  3. Translation generation

    In development, the pseudotranslator generates instant fake translations (no API calls). In CI, the configured LLM provider generates real translations with full component context - file location, surrounding elements, and interpolation semantics. Only new or changed strings are translated - the compiler uses content hashing to skip unchanged strings.

  4. Code injection

    Translation lookups are injected into your JSX. The compiler adds lightweight hash-based lookup calls against the embedded dictionary for each locale. Your source code is never modified.

  5. Bundle optimization

    Per-locale bundles are created. Only translations used by each component are included. Dead code elimination and tree-shaking keep bundles minimal.

Supported frameworks

Framework Integration
Next.js (App Router) withLingo() config wrapper - supports RSC, Webpack, and Turbopack
Vite + React lingoCompilerPlugin - Vite plugin with full HMR support

Key features

  • Automatic by default - all JSX text is translated unless you opt into 'use i18n' directive mode
  • No dictionary fetching - translations embedded in per-locale bundles, no separate files to load
  • Build modes - pseudotranslator in dev, real translations in CI, cache-only in production
  • Manual overrides - data-lingo-override attribute for precise control
  • Custom locale resolvers - implement your own locale detection and persistence
  • Automatic pluralization - ICU MessageFormat support for plural forms
  • Development tools - pseudotranslator and in-browser translation editor

Next Steps

Setup Add multilingual support in under 5 minutes Next.js Framework-specific integration guide Configuration Reference All configuration options Build Modes Dev, CI, and production workflows