Projektstruktur

Der Lingo.dev Compiler erstellt und verwaltet im Stammverzeichnis Ihres Projekts das Verzeichnis .lingo/, in dem Übersetzungsmetadaten und Cache gespeichert werden. Wenn Sie diese Verzeichnisstruktur verstehen, können Sie Übersetzungen in der Versionsverwaltung besser verwalten, fehlende Übersetzungen leichter debuggen und die Build-Performance optimieren.

Das Verzeichnis .lingo/#

Der Compiler erstellt dieses Verzeichnis beim ersten Build automatisch. Es enthält alle Übersetzungsmetadaten, die in der Build-Pipeline verwendet werden:

.lingo/
  metadata.json              # Translation cache and content hashes
  locale-resolver.server.ts  # Optional: custom server-side locale resolver
  locale-resolver.client.ts  # Optional: custom client-side locale resolver

metadata.json#

Dies ist die wichtigste Datei im Verzeichnis .lingo/. Sie speichert:

• Content-Hashes – Stabile, hashbasierte Kennungen für jede übersetzbare Zeichenfolge
• Zwischengespeicherte Übersetzungen – Generierte Übersetzungen für jedes Sprachpaar
• Quelltext-Snapshots – Der Quelltext zum Zeitpunkt der Übersetzung, um Änderungen zu erkennen

Der Compiler liest diese Datei zu Beginn jedes Builds. Zeichenfolgen mit übereinstimmenden Hashes verwenden zwischengespeicherte Übersetzungen wieder. Zeichenfolgen mit geänderten oder fehlenden Hashes werden an den konfigurierten Übersetzungsanbieter gesendet.

.gitignore-Hinweise#

Fügen Sie .lingo/ nicht zu .gitignore hinzu. Das Verzeichnis sollte in der Versionsverwaltung erfasst werden. Ein typisches .gitignore für ein Projekt, das den Compiler verwendet:

# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env

sourceRoot#

Die Option sourceRoot bestimmt, welches Verzeichnis der Compiler nach übersetzbaren React-Komponenten durchsucht:

{
  sourceRoot: "./app",  // Next.js App Router
  // or
  sourceRoot: "src",    // Vite + React
}

Der Compiler durchsucht rekursiv alle Dateien vom Typ .tsx, .ts, .jsx und .js innerhalb von sourceRoot nach übersetzbarem JSX-Inhalt. Dateien außerhalb dieses Verzeichnisses werden nicht verarbeitet.

Opt-in-Modus mit „use i18n“#

Standardmäßig übersetzt der Compiler den gesamten JSX-Text in sourceRoot. Um zum Opt-in-Modus zu wechseln, setzen Sie useDirective: true:

{
  useDirective: true,
}

Im Opt-in-Modus werden nur Dateien verarbeitet, die mit der Direktive 'use i18n' beginnen:

'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}

Dateien ohne diese Direktive werden übersprungen:

export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}

Wann Sie den Opt-in-Modus verwenden sollten#

lingoDir#

Die Option lingoDir ändert den Speicherort des Metadatenverzeichnisses:

{
  lingoDir: ".lingo",  // Default
  // or
  lingoDir: ".translations",  // Custom location
}

Das ist nützlich, wenn .lingo/ mit einem bestehenden Verzeichnis in Ihrem Projekt kollidiert.

Nächste Schritte#