Übersicht

Die Datei gt.config.json dient zur Konfiguration der GT-Einstellungen Ihres Projekts. Sie sollte im Projektstammverzeichnis 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 Standard-locale für Ihr Projekt. Das ist die locale, in der Ihre Quellinhalte verfasst sind. Sie dient außerdem als Standardwert-locale für Ihr Projekt (bei Verwendung von gt-next oder gt-react).

• locales: Ein Array von locales für Ihr Projekt. Das sind die locales, in die Sie Ihr Projekt übersetzen möchten. Weitere Informationen finden Sie unter unterstützte locales. Wenn Sie gt-next oder gt-react verwenden, sind dies auch die locales, die Ihre App unterstützt.

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

• stageTranslations: Ein optionales boolesches Flag, das angibt, ob Ihr Projekt für eine manuelle Prüfung konfiguriert ist.

• src: Ein optionales Array von Glob-Mustern für Ihre Quelldateien. Standardmäßig gesetzt auf:

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]

• dictionary: Eine optionale Zeichenkette, die den relativen Pfad zur Wörterbuchdatei angibt.

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

Hier ist ein Skeleton der gt.config.json-Datei:

{
  "$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 Sie ein Locale mit einem Alias versehen möchten (z. B. cn statt zh), können Sie eine benutzerdefinierte Zuordnung in der Datei gt.config.json festlegen.

{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

Sie können für die aliased locale auch unterschiedliche Attribute festlegen.

{
  "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 – alle werden dann übersetzt. Derzeit unterstützen wir die folgenden Dateitypen:

• gt: General Translation-Dateien.
• 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 Glob‑Mustern sein, die auf die Dateien passen, die Sie übersetzen möchten.

Sie müssen den Platzhalter [locale] in Ihren Glob‑Mustern verwenden, damit Quelldateien korrekt gefunden und übersetzte Dateien am richtigen Ort gespeichert werden. Das CLI‑Tool ersetzt den Platzhalter [locale] beim Suchen nach übersetzbaren Dateien durch den Wert von defaultLocale.

Das CLI‑Tool speichert übersetzte Dateien im entsprechenden Pfad und ersetzt dabei den Platzhalter [locale] durch den Ziel‑Locale‑Code.

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

exclude

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

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

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

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

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

transform

transform kann entweder eine Zeichenkette oder ein Objekt sein.

Wenn transform eine Zeichenkette ist, definiert es eine Umbenennung des Dateinamens. Es sollte ein Platzhalter * enthalten, der durch den ursprünglichen Dateinamen ersetzt wird (alles vor dem ersten .).

Wenn Sie beispielsweise möchten, dass die Erweiterung all Ihrer übersetzten Dateien .[locale].json statt .json lautet, können Sie die folgende Konfiguration verwenden:

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

Alternativ gilt: Wenn transform ein Objekt ist, sollte es 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 werden auf den vollständigen relativen Dateinamen der Ausgabedatei abgebildet.

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

Zum Beispiel bewirkt die obige Konfiguration, dass übersetzte Dateien in einem Unterverzeichnis der Ziel-Locale 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 locale code, der je nach Kontext unterschiedlich funktioniert:
  • In match-Strings: Wird durch den Standard-locale code ersetzt (z. B. "en"), um Quelldateien zu identifizieren
  • In replace-Strings: Wird durch den Ziel-locale code ersetzt (z. B. "fr", "es") für die übersetzten Ausgabedateien

Wenn z. B. dein Standard-locale "en" ist und du nach "fr" übersetzt:

• Ein match-Muster "content/{locale}/file.md" wird zu "content/en/file.md"
• Ein replace-Muster "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.

output

Dieser Schlüssel wird ausschließlich für General Translation files verwendet, insbesondere zum lokalen Speichern von Übersetzungen. Wenn Sie das GT CDN verwenden, ist dieser Schlüssel nicht erforderlich.

Die value sollte eine Zeichenfolge mit einem [locale]-Platzhalter sein, der den Speicherort angibt, an dem die Übersetzungen gespeichert werden.

Wenn Sie beispielsweise Ihre spanischen Übersetzungen in einer Datei namens ui.es.json im Verzeichnis public/i18n speichern möchten, sollten Sie die folgende Zeichenfolge verwenden:

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

Dateityp: gt

Unterstützte Schlüssel

• output (erforderlich)

Beispiel

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

Diese Konfiguration weist das CLI-Tool an, Ihre französischen und spanischen Übersetzungen im Verzeichnis public/i18n/[locale].json zu speichern.

Standardmäßig werden mit dieser Konfiguration keine Übersetzungen vom CLI-Tool im GT CDN veröffentlicht.

Dateityp: json

Unterstützte Schlüssel

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

Beispiel

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

Angenommen, die Standard-Locale Ihres Projekts ist en, und Sie möchten Ihr Projekt nach fr und es übersetzen.

Mit dieser Konfiguration sucht die CLI nach allen 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

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

Angenommen, die Standard-Locale Ihres Projekts ist en, und Sie möchten Ihr Projekt in fr und 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

{
  "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 suchen und die übersetzten Dateien im Verzeichnis content/docs/ja zu speichern.

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

Dateityp: md

Unterstützte Schlüssel

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

Beispiel

{
  "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 Dateierweiterung 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

{
  "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 Dateierweiterung der übersetzten Dateien von .js entsprechend auf .fr.js bzw. .es.js geändert wird.

Dateityp: ts

Unterstützte Schlüssel

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

Beispiel

{ 
  "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 sorgt dafür, dass die Endung der übersetzten Dateien entsprechend in .fr.ts bzw. .es.ts geändert wird (aus .ts).

Beispielkonfiguration

Schauen wir uns eine Beispiel-gt.config.json-Datei im Detail an:

{
  "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 (mit Ausnahme der Dateien im Verzeichnis resources/en/exclude).
• Alle Inline-<T>-Komponenten in Ihrem React- oder Next.js-Projekt.
• Ihre Datei dictionary.[json|js|ts].

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

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

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

Nächste Schritte

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