Übersetzen

So übersetzen Sie Ihr Projekt

Verwendung

Führen Sie dies in Ihrer CI-Pipeline aus, bevor Sie Ihre App für den Produktionsbetrieb builden.

npx gtx-cli translate

Hinweis: Dieser Befehl erfordert einen API-Schlüssel für die Produktion! Holen Sie sich einen im Dashboard.

Überblick

Der Befehl gtx-cli translate übersetzt Ihr Projekt. Er durchläuft den Dateibaum Ihres Projekts und übersetzt alle Inhalte, die in einer <T>‑Komponente gekennzeichnet sind oder die die Funktionen useGT verwenden.

Zusätzlich werden Inhalte aus der Wörterbuchdatei einbezogen (falls eine vorhanden ist).

Dieser Befehl ist der Hauptweg zur Nutzung der General Translation API und der zugehörigen Dienste.

Nur für den Produktionseinsatz!

Dieser Befehl ist für Produktions-Builds gedacht und sollte nicht in der Entwicklung verwendet werden. Bevor Sie diesen Befehl ausführen, vergewissern Sie sich, dass Sie auf dem Branch sind, der für die Produktion verwendet wird. Denken Sie daran, auch Ihren Produktions-API-Schlüssel (GT_API_KEY) und die Projekt-ID (GT_PROJECT_ID) in Ihren Umgebungsvariablen zu setzen.

Verwendung

Es gibt drei Möglichkeiten, den Befehl translate zu nutzen. Die Methoden 1 und 2 erfordern einen Produktions-API-Schlüssel:

Wir empfehlen, den Einrichtungsassistenten auszuführen: npx gtx-cli configure, um Ihr Projekt zu konfigurieren, bevor Sie den Befehl translate verwenden. Je nach Projektkonfiguration kann sich das Verhalten des Befehls translate unterscheiden.

Methode 1: Übersetzen Sie die JSON-Dateien Ihres Projekts.

Wenn Sie andere i18n-Bibliotheken wie next-intl, react-i18next oder next-i18next verwenden, können Sie diese Methode nutzen, um die JSON-Dateien Ihres Projekts zu übersetzen.

Die Übersetzungen werden automatisch in Ihrem Codebestand gespeichert.

Um das CLI-Tool zum Übersetzen der JSON-Dateien Ihres Projekts zu verwenden, passen Sie Ihre Datei gt.config.json an, sodass json in der Eigenschaft files enthalten ist. Weitere Details finden Sie in der CLI-Konfigurationsdokumentation.

npx gtx-cli translate

Das CLI-Tool erkennt Ihre i18n‑Bibliothek automatisch, indem es Ihre Datei package.json ausliest, und übersetzt Ihre JSON-Dateien unter Beachtung der Syntax Ihrer i18n‑Bibliothek.

Methode 2: Übersetzen Sie Ihr GT-Projekt.

Wenn Ihr Projekt gt-next oder gt-react verwendet, können Sie mit dieser Methode Übersetzungen für Ihr Projekt erzeugen.

npx gtx-cli translate

Standardmäßig werden Übersetzungen im GT CDN gespeichert.

Wenn Sie die Übersetzungen jedoch in Ihrem Codebasis speichern möchten, fügen Sie die Eigenschaft gt dem Objekt files in der Datei gt.config.json hinzu.

gt-next und gt-react unterstützen sowohl das lokale Ausliefern von Übersetzungen als auch die Nutzung des öffentlichen CDN von General Translation. Wir empfehlen die Nutzung des CDN für geringere Latenz, bessere Performance und kleinere Bundle-Größen.

Weitere Details finden Sie in der CLI-Konfigurationsdokumentation.

Methode 3: Validieren Sie die <T>-Komponenten und die Wörterbuchdatei Ihres Projekts.

Diese Methode ist hilfreich, um die <T>-Komponenten und die Wörterbuchdatei Ihres Projekts zu prüfen.

So wird sichergestellt, dass Ihr Projekt korrekt konfiguriert ist und die Übersetzungen gültig und präzise sind.

Es werden keine Übersetzungen erzeugt, wenn der --dry-run-Schalter verwendet wird.

npx gtx-cli translate --dry-run

Flags

ParameterBeschreibungTypOptionalStandardwert
--api-keyEinen Produktions-API-Schlüssel angebenstringtrue
--project-idDie Projekt-ID angebenstringtrue
--version-idEine Versions-ID angeben (standardmäßig ein Hash des Inhalts)stringtrue
--config <path>Einen Pfad zur GT-Konfigurationsdatei angebenstringtrue"gt.config.json"
--tsconfig, --jsconfig <path>Einen Pfad zur TS- oder JS-Konfigurationsdatei angebenstringtrue
--src <paths>Durch Leerzeichen getrennte Liste von Glob-Mustern zum Abgleichen von Quelldateien. Sollte relativ zum Projektstammverzeichnis sein.[string]true[ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ]
--dictionary <path>Einen Pfad zur Wörterbuchdatei angebenstringtrue
--inlineInline-<T>-Tags zusätzlich zum Wörterbuch einbeziehenbooleantruetrue
--timeoutZeitüberschreitung für die Übersetzungsanfrage in Sekundennumbertrue600
--new, --locales <locales>Ziel-Locales, in die Ihr Projekt übersetzt werden soll[string]true
--default-locale <locale>Die Quell-Locale für das Projektstringtrueen
--ignore-errorsFehler ignorieren und Übersetzungen für gültige Inhalte erzwingenflagtruefalse
--dry-runDen Befehl im Trockenlauf ausführenflagtruefalse
--forceEine erneute Übersetzung Ihres Projekts erzwingenflagtruefalse
--force-downloadDas Herunterladen aller Übersetzungen für das Projekt erzwingenflagtruefalse

Alle diese Parameter sind optional.

Fügen Sie Ihren API-Schlüssel nicht in die gt.config.json-Datei ein! Setzen Sie ihn stattdessen als Umgebungsvariable. Die CLI liest GT_API_KEY automatisch, wenn die Variable gesetzt ist.

Es gibt einige wichtige Parameter:

ParameterBeschreibung
--dry-runDieses Flag veranlasst die CLI, Ihr Projekt zu parsen und zu validieren, ohne mit der GT-API zu kommunizieren. Das ist nützlich, um Ihre Codebasis zu prüfen.
--api-keySofern Sie nicht --dry-run verwenden, müssen Sie einen Produktions-API-Schlüssel angeben.
--project-idEbenso müssen Sie, sofern Sie nicht --dry-run verwenden, eine Projekt-ID angeben.
--new, --locales <locales>Ziel-Locales, in die Ihr Projekt übersetzt werden soll. Diese werden an die in Ihrer gt.config.json-Datei angegebenen locales angehängt.
--forceDieses Flag erzwingt eine erneute Übersetzung Ihres Projekts und überschreibt alle vorhandenen Übersetzungen.
--force-downloadDieses Flag erzwingt das Herunterladen aller Übersetzungen und überschreibt alle Änderungen, die Sie lokal an den Übersetzungen vorgenommen haben.

Konfigurationsdatei

Wenn Sie das CLI-Tool zum ersten Mal ausführen, versucht es, im Projektstamm eine Datei gt.config.json zu erstellen. Diese Datei enthält Metadaten zu Ihrem Projekt, die zum Übersetzen Ihrer Inhalte verwendet werden.

Weitere Informationen zur Datei gt.config.json finden Sie hier.

Wichtige Hinweise

Inhaltsquellen

Der Befehl translate durchsucht Ihr Projekt rekursiv nach übersetzbarem Inhalt.

Standardmäßig sucht er in den folgenden Verzeichnissen:

  • ./src
  • ./app
  • ./pages
  • ./components

Sie können alternative Verzeichnisse angeben, indem Sie das Flag --src verwenden oder die Eigenschaft src in Ihrer Datei gt.config.json anpassen.

Überschreiben von Übersetzungen

Standardmäßig überschreibt das CLI-Tool keine lokal vorgenommenen Änderungen an Übersetzungen, es sei denn, der Quellinhalt hat sich geändert.

Wenn Sie bereits übersetzte Projektinhalte erneut übersetzen möchten, können Sie das Flag --force verwenden.

Die Verwendung von --force überschreibt alle vorhandenen Übersetzungen und verwirft alle lokal vorgenommenen Änderungen.

Wenn Sie die neuesten Projektübersetzungen bereits abgerufen haben und diese erneut herunterladen möchten, können Sie das Flag --force-download verwenden.

Die Verwendung von --force-download überschreibt alle lokal vorgenommenen Änderungen und ruft die aktuellsten Übersetzungen ab. Inhalte werden dabei nicht erneut übersetzt.

Wörterbuchdatei

Der Befehl translate erkennt die Wörterbuchdatei in Ihrem Projekt automatisch.

Standardmäßig sucht er in den folgenden Verzeichnissen nach einer Datei namens dictionary.[json|ts|js]:

  • ./src
  • ./

Sie können eine andere Wörterbuchdatei mit dem Flag --dictionary angeben oder die Eigenschaft dictionary in Ihrer Datei gt.config.json anpassen.

Wie ist dieser Leitfaden?

Übersetzen