Übersicht

Die Datei gt.config.json konfiguriert die 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. In dieser locale ist Ihr Quellinhalt verfasst. Sie dient auch 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 supported locales. Wenn Sie gt-next oder gt-react verwenden, sind dies auch die locales, die Ihre App unterstützt.

• files: Ein Objekt mit Informationen über die Inhalte, die Sie übersetzen möchten.

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

• src: Ein optionales Array von Datei-Globmustern für Ihre Quell-files. Standardmäßig eingestellt auf:

[
  "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.

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

Hier ist ein Skeleton der Datei 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 Sie eine locale aliassen 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 auch unterschiedliche Attribute für die aliased locale angeben.

{
  "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: General Translation files.
• json: JSON files.
• yaml: YAML files.
• mdx: Markdown-Komponenten (MDX) files.
• md: Markdown (MD) files.
• js: JavaScript files.
• ts: TypeScript files.

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-Patterns sein, die die files erfassen, die Sie übersetzen möchten.

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

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

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

exclude

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

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

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

Wenn Sie files für alle locales 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 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 Endung all Ihrer übersetzten files .[locale].json statt .json ist, 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 Strings; unterstützt Capture-Gruppen
• replace (erforderlich): String 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 oben genannte Konfiguration, dass übersetzte files in einem Unterverzeichnis der Ziel-locale gespeichert werden.

Spezielle Platzhalter

Die Transform-Option 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 beispielsweise dein Standard-locale "en" ist und du nach "fr" übersetzen möchtest:

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

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

output

Dieser Schlüssel wird ausschließlich für General Translation files verwendet, speziell zum lokalen Speichern von Übersetzungen. Wenn Sie das GT-CDN (Content Delivery Network) verwenden, wird dieser Schlüssel nicht benötigt.

Der value sollte eine Zeichenkette mit einem [locale]-Platzhalter sein, die 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 Zeichenkette 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 veröffentlicht das CLI-Tool Ihre Übersetzungen mit dieser Konfiguration nicht über das GT-CDN (Content Delivery Network).

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 auf fr und 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

{
  "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 nach 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 Keys

• 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 files im Verzeichnis content/docs/en zu durchsuchen und die übersetzten files im Verzeichnis content/docs/ja zu speichern.

Der Schlüssel transform bewirkt, dass die Erweiterung der übersetzten files 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, nach allen MD-Dateien im Verzeichnis content/docs/en zu suchen und die übersetzten Dateien im Verzeichnis content/docs/ja zu speichern.

Der Schlüssel transform bewirkt, dass die Dateiendung der übersetzten Dateien in .ja.md geändert wird.

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

Dateityp: js

Unterstützte Keys

• 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 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

{ 
  "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 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-Datei genauer 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 files mit einem einzigen Aufruf von gtx-cli translate:

• Alle MDX files im Verzeichnis content/docs/en.
• Alle JSON files im Verzeichnis resources/en (ausgenommen alle files 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 files können mit loadTranslations geladen werden.

MDX: Ü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: Ü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.