Projektstruktur

Verständnis des .lingo/-Verzeichnisses und seiner Inhalte.

Verzeichnisübersicht

Wenn Sie den Compiler zum ersten Mal ausführen, erstellt er ein .lingo/-Verzeichnis im Projektstamm:

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

Die Kerndatei, die alle Übersetzungsdaten enthält.

Struktur

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

Wichtige Felder

Version: Metadaten-Formatversion. Aktuell: "1"

Source/Target Locales: Ihre konfigurierten Locales

Translations: Hash-basiertes Mapping aller übersetzbaren Strings:

  • Hash (abc123def456): Stabiler Identifier basierend auf Quelltext + Kontext
  • source: Originaler englischer Text
  • context: Wo dieser Text erscheint (Datei, Zeile, Komponente)
  • locales: Übersetzungen für jede Ziel-Locale
  • metadata: Wann die Übersetzung erstellt/aktualisiert wurde

Hash-Generierung

Hashes sind deterministisch:

  • Basierend auf Quelltext + Komponenten-Kontext
  • Gleicher Text an verschiedenen Stellen = unterschiedliche Hashes
  • Ermöglicht kontextbewusste Übersetzungen

Beispiel:

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

Benutzerdefinierte Locale-Resolver

Optionale Dateien zur Anpassung der Locale-Erkennung und -Persistierung.

locale-resolver.server.ts

Serverseitige Locale-Erkennung (nur Next.js):

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

Clientseitige Locale-Erkennung und -Persistierung:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

Wenn diese Dateien nicht existieren, verwendet der Compiler das standardmäßige Cookie-basierte Verhalten.

Siehe Custom Locale Resolvers für Details.

Versionskontrolle

Sollten Sie .lingo/ committen?

Ja. Das .lingo/-Verzeichnis sollte versionskontrolliert werden:

Committen:

  • metadata.json — Enthält alle Übersetzungen
  • Custom Locale Resolvers (falls erstellt)

Nicht committen:

  • Nichts — alle Dateien in .lingo/ sollten committet werden

Warum Übersetzungen committen?

  1. Versionskontrolle — Übersetzungsänderungen zusammen mit Code nachverfolgen
  2. Team-Zusammenarbeit — Übersetzungen im Team teilen
  3. CI/CD — Produktions-Builds verwenden committete Übersetzungen
  4. Audit-Trail — Sehen, wann und warum Übersetzungen geändert wurden

Git-Integration

Fügen Sie .lingo/ zu Ihrem Repository hinzu:

git add .lingo/
git commit -m "chore: update translations"
git push

Der Compiler aktualisiert .lingo/metadata.json automatisch, wenn:

  • Neuer übersetzbarer Text hinzugefügt wird
  • Bestehender Text geändert wird
  • Übersetzungen generiert werden

Committen Sie diese Updates regelmäßig.

Dateigröße

metadata.json wächst mit Ihrer App:

  • Kleine App (50 Strings): ~10 KB
  • Mittlere App (500 Strings): ~100 KB
  • Große App (5000 Strings): ~1 MB

Dies ist normal und für die Versionskontrolle akzeptabel.

Aufräumen

Ungenutzte Übersetzungen entfernen

Im Laufe der Zeit können sich ungenutzte Übersetzungen ansammeln (von gelöschten Komponenten).

Manuelles Aufräumen:

  1. Suchen Sie nach dem Hash in Ihrer Codebasis
  2. Falls nicht gefunden, löschen Sie ihn aus metadata.json

Automatisiertes Aufräumen (demnächst verfügbar):

npx @lingo.dev/compiler clean

Dies entfernt ungenutzte Übersetzungen automatisch.

Übersetzungen zurücksetzen

Um alle Übersetzungen von Grund auf neu zu generieren:

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

Migration

Vom alten Compiler

Der alte Compiler verwendete eine andere Dateistruktur:

Alt:

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

Neu:

.lingo/
└── metadata.json

Die Migration ist nicht automatisiert. Details finden Sie im Migrationsleitfaden.

Übersetzungen inspizieren

Im Editor anzeigen

Öffnen Sie .lingo/metadata.json in Ihrem Editor:

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

Nach Übersetzung suchen

Übersetzung anhand des Quelltexts finden:

grep -r "Welcome" .lingo/metadata.json

Nach Hash suchen

grep -r "abc123" .lingo/metadata.json

Pretty Print

cat .lingo/metadata.json | jq '.'

Häufige Fragen

Kann ich metadata.json manuell bearbeiten? Ja, wird aber nicht empfohlen. Verwenden Sie stattdessen data-lingo-override – das ist sicherer und versionskontrolliert im Quellcode.

Was passiert, wenn ich metadata.json lösche? Der Compiler generiert sie beim nächsten Build neu. Alle Übersetzungen werden frisch generiert (verursacht API-Kosten).

Kann ich .lingo/ in ein anderes Verzeichnis verschieben? Ja. Konfigurieren Sie dies über die Option lingoDir:

{
  lingoDir: "translations"
}

Enthält metadata.json sensible Daten? Nein. Es enthält nur Quelltexte und Übersetzungen – keine API-Schlüssel oder Secrets.

Kann ich metadata.json aus mehreren Branches zusammenführen? Ja. Git führt Merges automatisch durch. Konflikte sind selten (Hashes sind eindeutig).

Was passiert, wenn zwei Branches dieselbe Übersetzung hinzufügen? Git führt sie automatisch zusammen. Wenn sich die Hashes unterscheiden (unterschiedlicher Kontext), werden beide beibehalten.

Nächste Schritte