i18n.json-Konfiguration

i18n.json ist eine Standard-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, Dateierkennungsmuster und die Konfiguration der KI-Übersetzungs-Engine in separate Abschnitte unterteilt. Dadurch verstehen Entwickler genau, wie ihr Lokalisierungs-Workflow funktioniert, indem sie die Konfigurationsdatei lesen.

Dieser Leitfaden 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 verstehen, wie jeder Abschnitt das Übersetzungsverhalten steuert.

Version

Das Feld version gibt die Version des Konfigurationsschemas 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.

Die 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 optional Regionscodes aus ISO 3166-1 integriert. Beispiele sind en, en-US, es-ES und zh-Hans.

Die 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  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

Falls Ihr Locale-Code nicht unterstützt wird, öffnen 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.

Befehle zur Sprachüberprüfung:

Provider-Konfiguration

Der Abschnitt provider legt fest, 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": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Für 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 tatsächliche Sprachcodes ersetzt.

Buckets-Konfiguration

Buckets definieren Dateierkennungsmuster und Verarbeitungsregeln. Jeder Bucket repräsentiert ein Dateiformat mit spezifischen Include/Exclude-Mustern.

{
  "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 Dateierkennungsmustern. 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 auf _ (Unterstrich) überschrieben werden. Überschreibt das Trennzeichen 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 sollen. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel. Verwenden Sie Sternchen *, um mehrere Schlüssel zu matchen.
    • buckets.[bucket-type].ignoredKeys — Array von Schlüsseln, die während der Übersetzung ignoriert werden sollen. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel. Verwenden Sie Sternchen *, um mehrere Schlüssel zu matchen.
    • buckets.[bucket-type].injectLocale — Array von Schlüsseln, bei denen der Locale-Code automatisch eingefügt werden soll. Verwendet Schrägstrich / als Trennzeichen für verschachtelte Schlüssel. Verwenden Sie Sternchen *, um mehrere Schlüssel zu matchen.

Grundlegende Musterstruktur

Include-Muster 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

Exclude-Muster verhindern die Verarbeitung bestimmter Dateien innerhalb von Include-Mustern.

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 sie in einem Monorepo-Setup verwenden können, in dem verschiedene Projekte unterschiedliche Trennzeichen-Konventionen 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-Catalog-Dateien
  • 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

Basiskonfiguration

{
  "$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 die Lingo.dev CLI eine ältere Konfigurationsversion erkennt:

  1. Erstellt ein Backup Ihrer aktuellen i18n.json Datei
  2. Migriert die Konfiguration auf die neueste 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 bei jedem CLI-Vorgang, der die Konfigurationsdatei liest. Es ist kein manueller Eingriff erforderlich, und Ihr Übersetzungs-Workflow läuft ohne Unterbrechung weiter.

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