i18n.json-Konfiguration

i18n.json ist die Konfigurationsdatei für die Lingo.dev CLI und CI/CD-Integrationen. Sie legt fest, welche Sprachen übersetzt werden, wo sich übersetzbare Inhalte befinden und welches Übersetzungs-Backend verwendet wird.

Minimales Beispiel#

json

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

Das Feld $schema aktiviert Autovervollständigung und Validierung in der IDE. Das Feld version erfasst die Schemaversion für die Kompatibilität mit automatischen Migrationen.

Sprache#

Der Abschnitt locale definiert die Quell- und Zielsprachen:

json

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

Feld	Beschreibung
`locale.source`	Die Sprache, in der Ihre Quellinhalte verfasst sind. Alle Übersetzungen gehen von dieser Sprache aus.
`locale.targets`	Array der Zielsprachen. Je nach Bucket-Format erzeugt jede Zielsprache eine separate Datei oder einen eigenen Abschnitt.

Sprachcodes folgen dem Standard BCP 47 – en, en-US, es-ES, zh-Hans und plattformspezifische Formate wie Androids en-rUS werden unterstützt.

So listen Sie verfügbare Sprachcodes auf:

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Buckets definieren Dateierkennungsmuster und Verarbeitungsregeln. Jeder Bucket-Schlüssel steht für ein Dateiformat, und sein Wert legt fest, welche Dateien ein- oder ausgeschlossen werden:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Feld	Beschreibung
`include`	Array von Dateimustern mit dem Platzhalter `[locale]`. Unterstützt Glob-Wildcards (`*`).
`exclude`	Optional. Array von Mustern, die bei der Verarbeitung übersprungen werden.
`lockedKeys`	Optional. Schlüssel, deren Werte ohne Übersetzung aus der Quelle übernommen werden. Siehe Key Locking.
`ignoredKeys`	Optional. Schlüssel, die vollständig von der Übersetzung ausgeschlossen sind – sie erscheinen nicht in den Zieldateien. Siehe Key Ignoring.
`preservedKeys`	Optional. Schlüssel, die einmal aus der Quelle initialisiert und anschließend vor automatischen Aktualisierungen geschützt werden. Siehe Key Preserving.
`injectLocale`	Optional. Schlüssel, in die der Ziel-Sprachcode automatisch eingefügt wird.

Include-Muster#

Include-Muster verwenden den Platzhalter [locale], der zur Laufzeit in Ihre konfigurierten Sprachcodes aufgelöst wird:

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

Rekursive Glob-Muster (**/*.json) werden nicht unterstützt. Verwenden Sie stattdessen explizite Verzeichnispfade.

Benutzerdefinierte Sprache-Trennzeichen#

Standardmäßig verwenden Sprachcodes in Dateinamen einen Bindestrich (-) als Trennzeichen: en-US.json. Wenn Sie stattdessen Unterstriche verwenden möchten, übergeben Sie ein Objekt mit dem Feld delimiter:

json

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

Dadurch wird legacy/en_US.json statt legacy/en-US.json erzeugt.

Schlüsselpfad-Notation#

Die Arrays lockedKeys, ignoredKeys und preservedKeys verwenden Schrägstrich-Notation (/) für verschachtelte Schlüssel und ein Sternchen (*) für Wildcards:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

Die vollständige Liste der unterstützten Bucket-Typen finden Sie unter Supported Formats.

Provider#

Der Abschnitt provider konfiguriert einen direkten LLM-Provider für Übersetzungen. Dieser Abschnitt ist optional – wenn er fehlt, verwendet die CLI eine Lokalisierungs-Engine auf Lingo.dev.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Feld	Beschreibung
`provider.id`	Provider-Kennung: `openai`, `anthropic`, `google`, `mistral`, `openrouter` oder `ollama`.
`provider.model`	Modellname des Providers (z. B. `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	System-Prompt. `{source}` und `{target}` werden zur Laufzeit durch Sprachcodes ersetzt.
`provider.baseUrl`	Optional. Benutzerdefinierter API-Endpunkt (für Ollama erforderlich: `http://localhost:11434`).

Engine-Anbindung#

Um Übersetzungen über eine bestimmte Lokalisierungs-Engine zu leiten, fügen Sie das Feld engineId hinzu:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Wenn engineId gesetzt ist, nutzt jede Übersetzungsanfrage automatisch die Markenstimme, das Glossar, die Anweisungen und die Modellkonfiguration Ihrer Engine. Wenn es fehlt und LINGO_API_KEY gesetzt ist, verwendet die CLI die Standard-Engine Ihrer Organisation.

Die vollständige Einrichtungsanleitung finden Sie unter Connect Your Engine.

Umgebungsvariablen#

Variable	Erforderlich	Beschreibung
`LINGO_API_KEY`	Für Lingo.dev Engine	Ihr Lingo.dev-API-Schlüssel.
`LINGO_API_URL`	Nein	Benutzerdefinierte API-Basis-URL (für Self-Hosting oder Staging).
`OPENAI_API_KEY`	Für den OpenAI-Provider	OpenAI-API-Schlüssel.
`ANTHROPIC_API_KEY`	Für den Anthropic-Provider	Anthropic-API-Schlüssel.
`GOOGLE_API_KEY`	Für den Google-Provider	Google-API-Schlüssel.
`MISTRAL_API_KEY`	Für den Mistral-Provider	Mistral-API-Schlüssel.
`OPENROUTER_API_KEY`	Für den OpenRouter-Provider	OpenRouter-API-Schlüssel.

Vollständiges Beispiel#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Versionsmigration#

Die CLI migriert ältere i18n.json-Konfigurationen automatisch auf die neueste Schemaversion. Sie erstellt eine Sicherungskopie Ihrer aktuellen Datei, aktualisiert das Schema und behält alle Einstellungen bei. Ein manuelles Eingreifen ist nicht erforderlich.

Nächste Schritte#

Supported Formats

Alle Bucket-Typen und ihre Konfiguration

i18n.lock

Wie die Lockdatei den Übersetzungsstatus nachverfolgt

Connect Your Engine

Leiten Sie Übersetzungen über Ihre Lokalisierungs-Engine

Setup

Installieren Sie die CLI und legen Sie los

Minimales Beispiel#

json

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

Das Feld $schema aktiviert Autovervollständigung und Validierung in der IDE. Das Feld version erfasst die Schemaversion für die Kompatibilität mit automatischen Migrationen.

Sprache#

Der Abschnitt locale definiert die Quell- und Zielsprachen:

json

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

Feld	Beschreibung
`locale.source`	Die Sprache, in der Ihre Quellinhalte verfasst sind. Alle Übersetzungen gehen von dieser Sprache aus.
`locale.targets`	Array der Zielsprachen. Je nach Bucket-Format erzeugt jede Zielsprache eine separate Datei oder einen eigenen Abschnitt.

Sprachcodes folgen dem Standard BCP 47 – en, en-US, es-ES, zh-Hans und plattformspezifische Formate wie Androids en-rUS werden unterstützt.

So listen Sie verfügbare Sprachcodes auf:

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Buckets definieren Dateierkennungsmuster und Verarbeitungsregeln. Jeder Bucket-Schlüssel steht für ein Dateiformat, und sein Wert legt fest, welche Dateien ein- oder ausgeschlossen werden:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Feld	Beschreibung
`include`	Array von Dateimustern mit dem Platzhalter `[locale]`. Unterstützt Glob-Wildcards (`*`).
`exclude`	Optional. Array von Mustern, die bei der Verarbeitung übersprungen werden.
`lockedKeys`	Optional. Schlüssel, deren Werte ohne Übersetzung aus der Quelle übernommen werden. Siehe Key Locking.
`ignoredKeys`	Optional. Schlüssel, die vollständig von der Übersetzung ausgeschlossen sind – sie erscheinen nicht in den Zieldateien. Siehe Key Ignoring.
`preservedKeys`	Optional. Schlüssel, die einmal aus der Quelle initialisiert und anschließend vor automatischen Aktualisierungen geschützt werden. Siehe Key Preserving.
`injectLocale`	Optional. Schlüssel, in die der Ziel-Sprachcode automatisch eingefügt wird.

Include-Muster#

Include-Muster verwenden den Platzhalter [locale], der zur Laufzeit in Ihre konfigurierten Sprachcodes aufgelöst wird:

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

Rekursive Glob-Muster (**/*.json) werden nicht unterstützt. Verwenden Sie stattdessen explizite Verzeichnispfade.

Benutzerdefinierte Sprache-Trennzeichen#

json

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

Dadurch wird legacy/en_US.json statt legacy/en-US.json erzeugt.

Schlüsselpfad-Notation#

Die Arrays lockedKeys, ignoredKeys und preservedKeys verwenden Schrägstrich-Notation (/) für verschachtelte Schlüssel und ein Sternchen (*) für Wildcards:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

Die vollständige Liste der unterstützten Bucket-Typen finden Sie unter Supported Formats.

Provider#

Der Abschnitt provider konfiguriert einen direkten LLM-Provider für Übersetzungen. Dieser Abschnitt ist optional – wenn er fehlt, verwendet die CLI eine Lokalisierungs-Engine auf Lingo.dev.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Feld	Beschreibung
`provider.id`	Provider-Kennung: `openai`, `anthropic`, `google`, `mistral`, `openrouter` oder `ollama`.
`provider.model`	Modellname des Providers (z. B. `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	System-Prompt. `{source}` und `{target}` werden zur Laufzeit durch Sprachcodes ersetzt.
`provider.baseUrl`	Optional. Benutzerdefinierter API-Endpunkt (für Ollama erforderlich: `http://localhost:11434`).

Engine-Anbindung#

Um Übersetzungen über eine bestimmte Lokalisierungs-Engine zu leiten, fügen Sie das Feld engineId hinzu:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Die vollständige Einrichtungsanleitung finden Sie unter Connect Your Engine.

Umgebungsvariablen#

Variable	Erforderlich	Beschreibung
`LINGO_API_KEY`	Für Lingo.dev Engine	Ihr Lingo.dev-API-Schlüssel.
`LINGO_API_URL`	Nein	Benutzerdefinierte API-Basis-URL (für Self-Hosting oder Staging).
`OPENAI_API_KEY`	Für den OpenAI-Provider	OpenAI-API-Schlüssel.
`ANTHROPIC_API_KEY`	Für den Anthropic-Provider	Anthropic-API-Schlüssel.
`GOOGLE_API_KEY`	Für den Google-Provider	Google-API-Schlüssel.
`MISTRAL_API_KEY`	Für den Mistral-Provider	Mistral-API-Schlüssel.
`OPENROUTER_API_KEY`	Für den OpenRouter-Provider	OpenRouter-API-Schlüssel.

Vollständiges Beispiel#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Versionsmigration#

Nächste Schritte#

Supported Formats

Alle Bucket-Typen und ihre Konfiguration

i18n.lock

Wie die Lockdatei den Übersetzungsstatus nachverfolgt

Connect Your Engine

Leiten Sie Übersetzungen über Ihre Lokalisierungs-Engine

Setup

Installieren Sie die CLI und legen Sie los