So funktioniert es

@lingo.dev/compiler transformiert Ihre React-Anwendung zur Build-Zeit durch intelligente Code-Analyse und KI-gestützte Übersetzung in eine mehrsprachige App.

Build-Zeit-Transformation

Traditionelle Runtime-i18n-Bibliotheken (i18next, react-intl) arbeiten zur Laufzeit – sie laden Übersetzungen, interpolieren Werte und formatieren Nachrichten, während Ihre App läuft. Dies erhöht die Bundle-Größe, den Runtime-Overhead und die Komplexität.

@lingo.dev/compiler funktioniert anders: Es transformiert Ihren Code während des Build-Prozesses. Ihre React-Komponenten bleiben sauber, und Übersetzungen werden in optimierte Bundles vorkompiliert.

Ergebnis: Null Runtime-Overhead, kleinere Bundles und keine manuelle Verwaltung von Übersetzungsschlüsseln.

Der Prozess

1. AST-Analyse

Der Compiler verwendet Babel, um Ihren React-Code in einen Abstract Syntax Tree (AST) zu parsen. Er durchläuft Ihr JSX und identifiziert übersetzbare Inhalte:

  • Textknoten (<p>Hello</p>)
  • String-Attribute (<img alt="Logo" />)
  • Text in Template-Ausdrücken (<p>Hello {name}</p>)

Der Compiler versteht React-Komponentengrenzen und behält kontextuelle Informationen für präzise Übersetzungen bei. Technische Bezeichner, Code-Snippets und nicht übersetzbare Elemente werden automatisch herausgefiltert.

2. Content-Extraktion

Für jeden übersetzbaren String führt der Compiler folgende Schritte aus:

  • Generiert einen stabilen hash-basierten Identifier
  • Bewahrt den Komponentenkontext (Datei, Position, umgebende Elemente)
  • Extrahiert Rich-Text-Struktur (verarbeitet verschachtelte Elemente wie <strong> und <em>)
  • Erhält Interpolations-Platzhalter

Diese Metadaten werden in .lingo/metadata.json gespeichert – einer versionierten Datei, die alle übersetzbaren Inhalte in Ihrer App verfolgt.

3. Übersetzungsgenerierung

Während der Entwicklung übernimmt der Translation-Server die On-Demand-Übersetzung:

  • Pseudotranslator-Modus (Standard): Generiert sofortige Fake-Übersetzungen – nützlich, um zu sehen, was übersetzt wird, ohne API-Kosten
  • Echter Übersetzungsmodus: Ruft Ihren konfigurierten LLM-Provider auf (Lingo.dev Engine oder direktes LLM)

Der Übersetzungsdienst ist zustandslos und behandelt partielle Fehler elegant – wenn einige Übersetzungen fehlschlagen, werden zwischengespeicherte Übersetzungen weiterhin verwendet.

4. Code-Injektion

Der Compiler injiziert Übersetzungs-Lookups in Ihr JSX:

// Your source code
<p>Hello {name}</p>

// Transformed code (simplified)
<p>{t('abc123', { name })}</p>

Die t()-Funktion ist optimiert und wird automatisch injiziert. Sie führt hash-basierte Lookups in vorgeladenen Übersetzungswörterbüchern durch.

5. Bundle-Optimierung

Zur Build-Zeit:

  • Pro-Locale-Bundles werden erstellt
  • Nur verwendete Übersetzungen werden eingeschlossen
  • Dead-Code-Elimination entfernt ungenutzte Übersetzungen
  • Wörterbücher werden pro Komponente tree-shaken

Entwicklungs-Workflow

Entwicklungsmodus

{
  dev: {
    usePseudotranslator: true,
  }
}

Wenn Sie npm run dev ausführen:

  1. Der Compiler startet einen Übersetzungsserver (findet automatisch Ports 60000-60099)
  2. Ihre App sendet Anfragen an den Server für Übersetzungen
  3. Pseudotranslator generiert sofortige Fake-Übersetzungen
  4. Übersetzungen werden in .lingo/metadata.json zwischengespeichert
  5. HMR funktioniert normal – der State bleibt erhalten

Das Entwicklungs-Widget (falls aktiviert) ermöglicht es Ihnen, Übersetzungen im Browser zu bearbeiten und Änderungen in Echtzeit zu sehen.

Produktionsmodus

{
  buildMode: "cache-only",
}

Wenn Sie npm run build ausführen:

  1. Kein Übersetzungsserver wird gestartet
  2. Nur zwischengespeicherte Übersetzungen aus .lingo/metadata.json werden verwendet
  3. Falls Übersetzungen fehlen, schlägt der Build mit klarer Fehlermeldung fehl
  4. Keine API-Aufrufe werden durchgeführt – keine API-Keys erforderlich

Warum nur Cache? In der Produktion möchten Sie deterministische Builds. Übersetzungen sollten in CI generiert werden (wo Sie API-Keys haben), nicht während Produktions-Builds.

Empfohlener Workflow

Lokale Entwicklung:

  • Pseudotranslator verwenden
  • Schnelle Feedback-Schleife
  • Keine API-Kosten

CI/CD:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}
  • Echte Übersetzungen generieren
  • Einmal pro Deployment ausführen
  • .lingo/-Änderungen committen

Produktions-Build:

{
  buildMode: "cache-only",
}
  • Verwendet vorgenerierte Übersetzungen
  • Keine API-Schlüssel erforderlich
  • Schnelle, deterministische Builds

Architektur

Der Compiler ist nach klarer Trennung der Zuständigkeiten organisiert:

Metadata Manager

  • CRUD-Operationen für .lingo/metadata.json
  • Thread-sicher mit Dateisperrung
  • Hash-basierte Identifikatoren für Übersetzungen

Translation Service

  • Orchestriert den Übersetzungs-Workflow
  • Verwaltet Cache-Strategie
  • Behandelt partielle Fehler
  • Gibt sowohl erfolgreiche Übersetzungen als auch Fehler zurück

Translators (zustandslos)

  • Pseudotranslator: Sofortige Fake-Übersetzungen
  • LCP Translator: Lingo.dev Engine-Integration
  • LLM Translators: Direkte Provider-Integration
  • Kein eingebautes Caching—Service-Layer übernimmt das

Translation Server

  • HTTP-Server für Entwicklung
  • WebSocket-Unterstützung für Echtzeit-Widget-Updates
  • Automatisches Port-Management
  • Batch-Request-Verarbeitung

Siehe die Source-Code-Architekturdokumentation für Implementierungsdetails.

Framework-Integration

Next.js

Der Compiler integriert sich über withLingo() Wrapper:

  • Unterstützt sowohl Webpack als auch Turbopack
  • Funktioniert mit React Server Components
  • Async-Config für Lazy-Plugin-Loading
  • Automatisches Locale-basiertes Routing (falls konfiguriert)

Vite

Der Compiler integriert sich über lingoCompilerPlugin:

  • Unplugin-basiert (funktioniert mit Vite, Webpack, Rollup)
  • Vollständige HMR-Unterstützung
  • Effiziente Dev-Server-Integration
  • Automatische Virtual-Module-Generierung

Häufige Fragen

Funktioniert das mit Server Components? Ja. In Next.js transformiert der Compiler sowohl Server- als auch Client-Components. Übersetzungs-Lookups funktionieren isomorph.

Was ist mit Code-Splitting? Übersetzungen werden automatisch zusammen mit Ihren Components aufgeteilt. Jeder Chunk enthält nur die Übersetzungen, die er benötigt.

Wie werden Übersetzungen gecacht? Alle Übersetzungen werden in .lingo/metadata.json gespeichert. Diese Datei ist versionskontrolliert und fungiert als Ihr Übersetzungs-Cache. Der Compiler verwendet Content-Hashes—nur neuer oder geänderter Text löst eine erneute Übersetzung aus.

Was passiert, wenn eine Übersetzung fehlschlägt? Der Service gibt Teilergebnisse zurück. Erfolgreiche Übersetzungen werden zwischengespeichert und verwendet, während Fehler mit Kontext für das Debugging protokolliert werden. Ihre App bricht nicht ab – sie greift auf zwischengespeicherte Übersetzungen oder den Quelltext zurück.

Kann ich den transformierten Code sehen? Ja. Suchen Sie in Ihrer Build-Ausgabe nach den transformierten Dateien. Die Transformationen sind minimal – nur t()-Funktionsaufrufe mit hash-basierten Lookups.

Nächste Schritte