i18n.json Konfiguration

i18n.json ist eine standardmäßige Konfigurationsdatei, die das Verhalten der Lingo.dev CLI und der Lingo.dev CI/CD Integrationen steuert.

i18n.json implementiert eine schema-gesteuerte Konfiguration, die Spracheinstellungen, Dateisuchmuster und KI-Übersetzungsmotor-Konfiguration in separate Abschnitte unterteilt. Dadurch können Entwickler genau verstehen, wie ihr Lokalisierungs-Workflow funktioniert, indem sie die Konfigurationsdatei lesen.

Diese Anleitung setzt voraus, dass Sie die Lingo.dev CLI installiert haben und einen Übersetzungs-Workflow konfigurieren. Nach Abschluss werden Sie die vollständige i18n.json-Struktur, Konfigurationsoptionen und wie jeder Abschnitt das Übersetzungsverhalten steuert, verstehen.

Version

Das Feld version gibt die Konfigurationsschema-Version an:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10"
}

Konfigurationselemente:

  • $schema — Verweist auf die JSON-Schema-Definition für IDE-Autovervollständigung und Validierung. Das Schema hilft, Konfigurationsfehler frühzeitig zu erkennen, indem es Inline-Dokumentation und Typprüfung bereitstellt.
  • version — Konfigurationsschema-Version für Migrationskompatibilität.

Lingo.dev CLI verwendet dieses Feld für die automatische Konfigurationsmigration, wenn neue Schema-Versionen veröffentlicht werden.

Locale-Konfiguration

Der Abschnitt locale definiert, welche Sprachen die Lingo.dev CLI verarbeitet:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

Sprachcodes folgen dem BCP 47-Standard für Sprach-Tags, der Sprachcodes aus ISO 639 und optionale Regionscodes aus ISO 3166-1 enthält. Beispiele sind en, en-US, es-ES und zh-Hans.

Lingo.dev CLI unterstützt auch plattformspezifische Locale-Formate wie Androids en-rUS-Konvention für Ressourcenverzeichnisse. Um die vollständige Liste der unterstützten Locale-Codes zu erhalten, führen Sie aus:

npx lingo.dev@latest show locale sources  # Verfügbare Quellsprachen
npx lingo.dev@latest show locale targets  # Verfügbare Zielsprachen

Wenn Ihr Locale-Code nicht unterstützt wird, erstellen Sie bitte einen Pull Request, um ihn hinzuzufügen!

Konfigurationselemente:

  • locale.source — Quellsprachcode, der identifiziert, welche Dateien den maßgeblichen Inhalt enthalten. Alle Übersetzungen fließen von der Quelle zu den Zielen.
  • locale.targets — Array von Zielsprachcodes, die Ihre Zielmärkte repräsentieren. Jeder Code entspricht einer separaten Datei oder einem Abschnitt innerhalb einer Datei, abhängig vom Format.

Sprachverifizierungsbefehle:

Provider-Konfiguration

Der Abschnitt provider bestimmt, welchen KI-Übersetzungsdienst die Lingo.dev CLI verwendet. Dieser Abschnitt ist optional und verwendet standardmäßig die KI-Übersetzungs-Engine von Lingo.dev, wenn er weggelassen wird.

Für direkten LLM-API-Zugriff:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Ihr benutzerdefinierter Übersetzungsprompt mit {source} und {target} Platzhaltern"
  }
}

Für die Lingo.dev Engine:

Um die Lingo.dev Engine zu verwenden, lassen Sie den Provider-Abschnitt vollständig weg. Die Engine wählt automatisch Modelle und Prompts basierend auf Optimierungsforschung und Ihren Lingo.dev Engine-Einstellungen aus.

Konfigurationselemente:

  • provider.id — Kennung des KI-Übersetzungsdienstes (z.B. "openai" oder "anthropic").
  • provider.model — Name des KI-Übersetzungsmodells (z.B. "gpt-4o-mini" für OpenAI oder "claude-3-haiku" für Anthropic).
  • provider.prompt — System-Prompt, der das Übersetzungsverhalten steuert. Die Platzhalter {source} und {target} werden zur Laufzeit durch die tatsächlichen Sprachcodes ersetzt.

Buckets-Konfiguration

Buckets definieren Muster für die Dateierkennung und Verarbeitungsregeln. Jeder Bucket repräsentiert ein Dateiformat mit spezifischen Einschluss-/Ausschlusskriterien.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings/language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Konfigurationselemente:

  • buckets.[bucket-type] — Konfigurationsgruppe für einen spezifischen Dateiformat-Bucket.
    • buckets.[bucket-type].include — Array von Dateientdeckungsmustern. Kann Strings oder Objekte enthalten.
      • buckets.[bucket-type].include.[string] — Einfaches Dateipfadmuster mit [locale]-Platzhalter.
      • buckets.[bucket-type].include.[object] — Erweiterte Musterkonfiguration mit folgenden Eigenschaften:
        • path — Das Dateipfadmuster mit [locale]-Platzhalter.
        • delimiter — Das Trennzeichen für Locale-Codes. Standardmäßig - (Bindestrich), kann zu _ (Unterstrich) überschrieben werden. Überschreibt den Delimiter aus der Locale-Konfiguration.
    • buckets.[bucket-type].exclude — Array von Dateiausschlussmustern, die während der Verarbeitung übersprungen werden sollen.
    • buckets.[bucket-type].lockedKeys — Array von Schlüsseln, die nicht übersetzt werden sollten. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel.
    • buckets.[bucket-type].ignoredKeys — Array von Schlüsseln, die während der Übersetzung ignoriert werden sollten. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel.
    • buckets.[bucket-type].injectLocale — Array von Schlüsseln, in die der Locale-Code automatisch eingefügt werden soll. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel.

Grundlegende Musterstruktur

Einschlussmuster verwenden eine Glob-ähnliche Syntax mit dem speziellen Platzhalter [locale]:

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Ausschlussmuster verhindern die Verarbeitung bestimmter Dateien innerhalb von Einschlussmustern.

Erweiterte Musteroptionen

Benutzerdefinierte Locale-Trennzeichen für verschiedene Dateinamenformate:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

Verfügbare Trennzeichen:

  • - (Bindestrich): en-US.json
  • _ (Unterstrich): en_US.json

Tipp: Diese Einstellung steuert das im Dateinamen verwendete Trennzeichen, sodass Sie es in einem Monorepo-Setup verwenden können, bei dem verschiedene Projekte unterschiedliche Trennzeichenkonventionen haben.

Unterstützte Bucket-Typen

Lingo.dev CLI unterstützt die folgenden Bucket-Typen für verschiedene Dateiformate:

  • android — Android XML-Ressourcendateien
  • csv — CSV-Dateien mit separaten Dateien für jede Zielsprache
  • flutter — Flutter ARB-Dateien
  • html — HTML-Dateien mit separaten Dateien für jede Zielsprache
  • json — JSON-Dateien mit separaten Dateien für jede Zielsprache
  • markdown — Markdown-Dateien mit separaten Dateien für jede Zielsprache
  • mdx — MDX-Dateien mit separaten Dateien für jede Zielsprache
  • xcode-strings — Legacy Xcode .strings-Dateien
  • xcode-stringsdict — Xcode .stringsdict-Dateien für Pluralisierung
  • xcode-xcstrings — Xcode Strings-Katalogdateien
  • yaml — YAML-Dateien mit separaten Dateien für jede Zielsprache
  • yaml-root-key — YAML-Dateien mit Locale-basierten Root-Keys
  • properties — Java .properties-Dateien
  • po — GNU gettext .po-Dateien
  • xml — Generische XML-Dateien mit separaten Dateien für jede Zielsprache
  • php — PHP-Array-Dateien
  • vue-json — Vue.js i18n JSON-Dateien
  • typescript — TypeScript-Dateien mit separaten Dateien für jede Zielsprache

Konfigurationsbeispiele

Grundkonfiguration

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Monorepo-Konfiguration

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

Versionsmigration

i18n.json implementiert eine intelligente Versionsmigration, die Ihre Konfiguration automatisch auf neuere Schema-Versionen aktualisiert und dabei alle Benutzereinstellungen beibehält.

Wenn Lingo.dev CLI eine ältere Konfigurationsversion erkennt:

  1. Erstellt es ein Backup Ihrer aktuellen i18n.json-Datei
  2. Migriert die Konfiguration zur neuesten Schema-Version
  3. Bewahrt alle Einstellungen einschließlich benutzerdefinierter Provider, Bucket-Konfigurationen und gesperrter Schlüssel
  4. Aktualisiert das Versionsfeld entsprechend dem aktuellen Schema

Migrationsverhalten:

Die Migration wird automatisch ausgelöst während jeder CLI-Operation, die die Konfigurationsdatei liest. Kein manuelles Eingreifen ist erforderlich, und Ihr Übersetzungsworkflow läuft ohne Unterbrechung weiter.

Dieses Migrationssystem stellt sicher, dass i18n.json-Konfigurationen mit Lingo.dev CLI-Updates kompatibel bleiben und gleichzeitig die Abwärtskompatibilität mit bestehenden Projekten gewährleistet wird.