Lingo.dev Compiler

Max Prilutskiy·Updated2 months ago·3 min read

Alpha

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

// 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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