Dashboard

Konfiguration

Konfigurationsdokumentation für die Datei gt.config.json

Übersicht

Die Datei gt.config.json dient zur Konfiguration der GT-Einstellungen Ihres Projekts. Sie sollte im Stammverzeichnis des Projekts liegen.

Der CLI-Einrichtungsassistent npx gtx-cli init erstellt die Datei gt.config.json automatisch in Ihrem Projekt.

Konfiguration

Die Datei gt.config.json akzeptiert unter anderem die folgenden Eigenschaften:

  • defaultLocale: Die Standardsprache (Locale) deines Projekts. In dieser Sprache ist dein Quellinhalt verfasst. Gleichzeitig dient sie als Fallback-Locale für dein Projekt (bei Verwendung von gt-next oder gt-react).

  • locales: Ein Array der Locales deines Projekts. Das sind die Sprachen, in die du dein Projekt übersetzen möchtest. Siehe die unterstützten Locales für weitere Informationen. Wenn du gt-next oder gt-react verwendest, sind dies außerdem die Locales, die deine App unterstützt.

  • files: Ein Objekt mit Informationen zu den Inhalten, die du übersetzen möchtest.

  • stageTranslations: Ein optionales boolesches Flag, das angibt, ob dein Projekt für eine menschliche Überprüfung konfiguriert ist.

  • src: Ein optionales Array von Dateiglobmustern für deine Quelldateien. Standardmäßig:

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
  • dictionary: Ein optionaler String, der den relativen Pfad zur Wörterbuchdatei angibt.

Zur Validierung deiner gt.config.json kannst du das JSON Schema für die CLI verwenden.

Füge es am Anfang deiner gt.config.json ein:

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

Hier ist ein Grundgerüst der Datei gt.config.json:

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "..."
    },
    "json": {
      "include": [...]
    },
    "mdx": {
      "include": [...]
    },
    "md": {
      "include": [...]
    }
  },
  "src": [
    "src/**/*.{ts,tsx}",
  ],
  "dictionary": "./dictionary.json"
}

Locale-Aliasing

Wenn du ein Locale aliasen möchtest (z. B. cn statt zh), kannst du eine benutzerdefinierte Zuordnung in der Datei gt.config.json festlegen.

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

Du kannst auch unterschiedliche Attribute für das aliasede Locale festlegen.

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin",
    }
  }
}

files

Unterstützte Dateitypen

files sollte für jeden Dateityp, den Sie übersetzen möchten, einen Schlüssel enthalten. Sie können Ihr Projekt so konfigurieren, dass verschiedene Dateitypen kombiniert werden und alle übersetzt werden. Derzeit unterstützen wir die folgenden Dateitypen:

  • gt: Allgemeine Übersetzungsdateien.
  • json: JSON-Dateien.
  • yaml: YAML-Dateien.
  • mdx: Markdown-Komponenten (MDX)-Dateien.
  • md: Markdown-(MD)-Dateien.
  • js: JavaScript-Dateien.
  • ts: TypeScript-Dateien.

Jeder Dateityp sollte einem Objekt entsprechen, das einen oder mehrere der folgenden Schlüssel enthält:

  • include
  • exclude
  • transform
  • output

include

Wenn verwendet, sollte der Wert des Schlüssels include ein Array von Globmustern sein, die die Dateien abdecken, die Sie übersetzen möchten.

Sie müssen den Platzhalter [locale] in Ihren Globmustern verwenden, damit Quelldateien korrekt gefunden und übersetzte Dateien am richtigen Ort gespeichert werden. Das CLI-Tool ersetzt den Platzhalter [locale] durch den Wert von defaultLocale, wenn nach übersetzbaren Dateien gesucht wird.

Das CLI-Tool speichert übersetzte Dateien im entsprechenden Pfad, wobei der Platzhalter [locale] durch den Zielsprachcode ersetzt wird.

{
  "include": ["docs/[locale]/**/*.json"]
}

exclude

Wenn verwendet, sollte der Wert des Schlüssels exclude ein Array aus Globmustern sein, die den Dateien entsprechen, die Sie von der Übersetzung ausschließen möchten.

Das Muster entspricht dem include-Muster, mit der Ausnahme, dass der Platzhalter [locale] optional ist. Wenn er angegeben ist, wird er durch den Wert von defaultLocale ersetzt.

{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}

Wenn Sie Dateien für alle Gebietsschemata von der Übersetzung ausschließen möchten, können Sie den Platzhalter [locales] anstelle von [locale] verwenden.

{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}

transform

transform kann entweder eine Zeichenkette oder ein Objekt sein.

Wenn transform eine Zeichenkette ist, definiert sie eine Neuzuordnung des Dateinamens. Sie sollte ein Platzhalterzeichen * enthalten, das durch den ursprünglichen Dateinamen ersetzt wird (alles vor dem ersten .).

Wenn du zum Beispiel möchtest, dass die Endung all deiner übersetzten Dateien .[locale].json statt .json ist, kannst du die folgende Konfiguration verwenden:

{
  "transform": "*.[locale].json"
}

Alternativ sollte transform, wenn es ein Objekt ist, die folgenden Eigenschaften enthalten:

  • match (optional): Ein Regex-Muster zum Abgleichen von Zeichenketten; unterstützt Capture-Gruppen
  • replace (erforderlich): Zeichenkette oder Regex-Muster, mit dem der Treffer ersetzt wird

Beide Werte unterstützen Regex-Capture-Gruppen und beziehen sich auf den vollständigen relativen Dateinamen der Ausgabedatei.

{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}

Die obige Konfiguration bewirkt zum Beispiel, dass übersetzte Dateien in einem Unterverzeichnis der Ziel-Lokalisierung gespeichert werden.

Spezielle Platzhalter

Die Option transform unterstützt mehrere spezielle Platzhalter, die sowohl in match- als auch in replace-Strings verwendet werden können:

  • {locale}: Der Platzhalter für den Sprach-/Ländercode, der je nach Kontext unterschiedlich gehandhabt wird:
    • In match-Strings: Wird durch den Standardcode (z. B. "en") ersetzt, um Quelldateien zu identifizieren
    • In replace-Strings: Wird durch den Zielcode (z. B. "fr", "es") ersetzt, um die übersetzten Ausgabedateien zu erzeugen

Wenn beispielsweise Ihr Standardcode "en" ist und Sie nach "fr" übersetzen:

  • Ein match-Muster wie "content/{locale}/file.md" wird zu "content/en/file.md"
  • Ein replace-Muster wie "content/{locale}/file.md" wird zu "content/fr/file.md"

Zusätzlich kann jede andere Eigenschaft aus getLocaleProperties() als Platzhalter mit demselben kontextabhängigen Verhalten verwendet werden.

Dies ist hilfreich, wenn Ihre Doku oder Ihr i18n-Framework für übersetzte Dateien eine bestimmte Dateiendung statt einer auf Unterverzeichnissen basierenden Locale-Routing-Struktur verlangt.

output

Dieser Schlüssel wird ausschließlich für General-Translation-Dateien verwendet, speziell zum lokalen Speichern von Übersetzungen. Wenn du das GT-CDN verwendest, wird dieser Schlüssel nicht benötigt.

Der Wert sollte eine Zeichenfolge mit dem Platzhalter [locale] sein, der den Ort angibt, an dem die Übersetzungen gespeichert werden.

Wenn du zum Beispiel deine spanischen Übersetzungen in einer Datei namens ui.es.json im Verzeichnis public/i18n speichern möchtest, solltest du die folgende Zeichenfolge verwenden:

{
  "output": "public/i18n/[locale].json"
}

Diese Option sollte nur verwendet werden, wenn du gt-next oder gt-react nutzt und Übersetzungen lokal speichern möchtest, statt das GT-CDN zu verwenden.

Derzeit kann nur eine Datei pro Locale erzeugt werden.

Dateityp: gt

Unterstützte Schlüssel

  • output (erforderlich)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
  }
}

Mit dieser Konfiguration speichert das CLI-Tool deine französischen und spanischen Übersetzungen im Verzeichnis public/i18n/[locale].json.

Standardmäßig veröffentlicht das CLI-Tool mit dieser Konfiguration deine Übersetzungen nicht im GT-CDN.

Dateityp: json

Unterstützte Schlüssel

  • include (Erforderlich)
  • exclude (Optional)
  • transform (Optional)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}

Angenommen, die Standardsprache deines Projekts ist en und du möchtest dein Projekt ins Französische (fr) und Spanische (es) übersetzen.

Mit dieser Konfiguration durchsucht die CLI alle JSON-Dateien im Unterverzeichnis json_files/en/ und speichert die übersetzten Dateien in json_files/fr/ und json_files/es/.

Dateien im Unterverzeichnis json_files/en/exclude/ werden ignoriert.

Dateityp: yaml

Unterstützte Schlüssel

  • include (Erforderlich)
  • exclude (Optional)
  • transform (Optional)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}

Angenommen, die Standardsprache Ihres Projekts ist en und Sie möchten Ihr Projekt ins Französische (fr) und Spanische (es) übersetzen.

Mit dieser Konfiguration durchsucht die CLI alle YAML-Dateien im Unterverzeichnis yaml_files/en/ und speichert die übersetzten Dateien in yaml_files/fr/ und yaml_files/es/.

Dateien im Unterverzeichnis yaml_files/en/exclude/ werden ignoriert.

Dateityp: mdx

Unterstützte Schlüssel

  • include (Erforderlich)
  • exclude (Optional)
  • transform (Optional)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}

Diese Konfiguration weist das CLI-Tool an, alle MDX-Dateien im Verzeichnis content/docs/en zu durchsuchen und die übersetzten Dateien im Verzeichnis content/docs/ja zu speichern.

Der Schlüssel transform sorgt dafür, dass die Erweiterung der übersetzten Dateien zu .ja.mdx geändert wird.

Dateityp: md

Unterstützte Schlüssel

  • include (erforderlich)
  • exclude (optional)
  • transform (optional)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}

Diese Konfiguration weist das CLI-Tool an, alle MD-Dateien im Verzeichnis content/docs/en zu durchsuchen und die übersetzten Dateien im Verzeichnis content/docs/ja zu speichern.

Der Schlüssel transform sorgt dafür, dass die Erweiterung der übersetzten Dateien in .ja.md geändert wird.

Alle Dateien im Verzeichnis content/docs/en/exclude werden ignoriert.

Dateityp: js

Unterstützte Schlüssel

  • include (Erforderlich)
  • exclude (Optional)
  • transform (Optional)

Beispiel

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}

Diese Konfiguration weist das CLI-Tool an, alle JavaScript-Dateien im Verzeichnis scripts/en zu durchsuchen und die übersetzten Dateien in den Verzeichnissen scripts/fr und scripts/es zu speichern.

Der Schlüssel transform sorgt dafür, dass die Erweiterung der übersetzten Dateien jeweils von .js auf .fr.js bzw. .es.js geändert wird.

Dateityp: ts

Unterstützte Schlüssel

  • include (Erforderlich)
  • exclude (Optional)
  • transform (Optional)

Beispiel

gt.config.json
{ 
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}

Diese Konfiguration weist das CLI-Tool an, alle TypeScript-Dateien im Verzeichnis scripts/en zu durchsuchen und die übersetzten Dateien in den Verzeichnissen scripts/fr und scripts/es zu speichern.

Der Schlüssel transform bewirkt, dass die Dateiendung der übersetzten Dateien entsprechend in .fr.ts bzw. .es.ts geändert wird (aus .ts).

Beispielkonfiguration

Sehen wir uns eine Beispiel-gt.config.json genauer an:

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    },
    "json": {
      "include": ["resources/[locale]/**/*.json"],
      "exclude": ["resources/[locale]/exclude/**/*.json"]
    }
  }
}

In diesem Beispiel übersetzen wir die folgenden Dateien mit einem einzigen Aufruf von gtx-cli translate:

  • Alle MDX-Dateien im Verzeichnis content/docs/en.
  • Alle JSON-Dateien im Verzeichnis resources/en (ausgenommen Dateien im Verzeichnis resources/en/exclude).
  • Alle Inline-<T>-Komponenten in Ihrem React- oder Next.js-Projekt.
  • Ihre Datei dictionary.[json|js|ts].

GT: Übersetzungen werden in public/i18n/es.json und public/i18n/fr.json gespeichert. Diese Dateien können mit loadTranslations() geladen werden.

MDX: Übersetzungen werden in den Verzeichnissen content/docs/fr und content/docs/es gespeichert. Die Dateierweiterungen werden entsprechend von .mdx auf .fr.mdx bzw. .es.mdx geändert.

JSON: Übersetzungen werden in den Verzeichnissen resources/fr und resources/es gespeichert.

Nächste Schritte

Erfahren Sie, wie Sie den Befehl init verwenden, um diese Konfigurationsdatei zu erstellen.

Wie ist dieser Leitfaden?

Auf GitHub bearbeiten

Auf dieser Seite

Übersicht
Konfiguration
Locale-Aliasing
files
Unterstützte Dateitypen
include
exclude
transform
Spezielle Platzhalter
output
Dateityp: gt
Dateityp: json
Dateityp: yaml
Dateityp: mdx
Dateityp: md
Dateityp: js
Dateityp: ts
Beispielkonfiguration
Nächste Schritte
Konfiguration