Übersetzen
So übersetzen Sie Ihr Projekt
Verwendung
Führen Sie dies in Ihrer CI-Pipeline aus, bevor Sie Ihre App für die Produktion builden.
npx gtx-cli translateHinweis: Dieser Befehl erfordert einen Produktions-API-Schlüssel! Du erhältst ihn im Dashboard.
Übersicht
Der Befehl gtx-cli translate übersetzt Ihr Projekt.
Er durchläuft den Dateibaum Ihres Projekts und übersetzt alle Inhalte, die in eine <T>-Komponente eingebettet sind
oder die useGT-Funktionen verwenden.
Zusätzlich werden Inhalte aus der Wörterbuchdatei einbezogen (falls eine vorhanden ist).
Dieser Befehl ist die primäre Methode zur Nutzung der General Translation API und zugehöriger 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, stellen Sie bitte sicher, dass Sie sich auf dem Branch befinden, der für die Produktion verwendet wird.
Denken Sie außerdem daran, 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.
Übersetzungen werden automatisch in Ihrem Code-Repository gespeichert.
Um das CLI-Tool zu verwenden, um die JSON-Dateien Ihres Projekts zu übersetzen, passen Sie Ihre gt.config.json an, sodass json in der Eigenschaft files enthalten ist.
Weitere Details finden Sie in der CLI-Konfigurationsdokumentation.
npx gtx-cli translateDas CLI-Tool erkennt Ihre i18n-Bibliothek automatisch, indem es Ihre package.json liest, 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 translateStandardmäßig werden Übersetzungen im GT-CDN gespeichert.
Wenn Sie die Übersetzungen jedoch in Ihrem Codebase speichern möchten, fügen Sie die Eigenschaft gt zum 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 (Content Delivery Network) 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 eignet sich, um die <T>-Komponenten und die Wörterbuchdatei Ihres Projekts zu validieren.
So stellen Sie sicher, dass Ihr Projekt korrekt konfiguriert ist und die Übersetzungen gültig und präzise sind.
Es werden keine Übersetzungen generiert, wenn der Schalter --dry-run angegeben ist.
npx gtx-cli translate --dry-runFlags
| Parameter | Beschreibung | Typ | Optional | Standard |
|---|---|---|---|---|
--api-key | Produktions-API-Schlüssel angeben | string | true | |
--project-id | Projekt-ID angeben | string | true | |
--version-id | Versions-ID angeben (standardmäßig ein Hash des Inhalts) | string | true | |
--config <path> | Pfad zur GT-Konfigurationsdatei angeben | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Pfad zur TS- oder JS-Konfigurationsdatei angeben | string | true | |
--src <paths> | Durch Leerzeichen getrennte Liste von Glob-Mustern für Quelldateien. Sollte relativ zum Root-Verzeichnis 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> | Pfad zur Wörterbuchdatei angeben | string | true | |
--inline | Inline-<T>-Tags zusätzlich zum Wörterbuch berücksichtigen | boolean | true | true |
--timeout | Zeitüberschreitung für die Übersetzungsanfrage in Sekunden | number | true | 600 |
--new, --locales <locales> | Locales, in die Ihr Projekt übersetzt werden soll | [string] | true | |
--default-locale <locale> | Quell-Locale für das Projekt | string | true | en |
--ignore-errors | Fehler ignorieren und Übersetzung für gültige Inhalte erzwingen | flag | true | false |
--dry-run | Befehl als Trockendurchlauf ausführen | flag | true | false |
--force | Erneute Übersetzung Ihres Projekts erzwingen | flag | true | false |
--force-download | Herunterladen aller Übersetzungen für das Projekt erzwingen | flag | true | false |
Alle diese Parameter sind optional.
Fügen Sie Ihren API-Schlüssel nicht in die Datei gt.config.json ein!
Setzen Sie ihn stattdessen als Umgebungsvariable. Die CLI liest automatisch GT_API_KEY, falls gesetzt.
Es gibt einige wichtige Parameter:
| Parameter | Beschreibung |
|---|---|
--dry-run | Dieses Flag veranlasst die CLI, Ihr Projekt zu parsen und zu validieren, kommuniziert jedoch nicht mit der GT-API. Nützlich zur Validierung Ihrer Codebasis. |
--api-key | Sofern Sie nicht --dry-run verwenden, müssen Sie einen Produktions-API-Schlüssel angeben. |
--project-id | Ebenso müssen Sie, sofern Sie nicht --dry-run verwenden, eine Projekt-ID angeben. |
--new, --locales <locales> | Locales, in die Ihr Projekt übersetzt werden soll. Diese werden an die in Ihrer Datei gt.config.json angegebenen Locales angehängt. |
--force | Dieses Flag erzwingt eine erneute Übersetzung Ihres Projekts und überschreibt alle vorhandenen Übersetzungen. |
--force-download | Dieses Flag erzwingt das Herunterladen aller Übersetzungen und überschreibt alle lokalen Änderungen, die Sie an den Übersetzungen vorgenommen haben. |
Konfigurationsdatei
Beim ersten Ausführen des CLI-Tools wird versucht, im Stammverzeichnis Ihres Projekts 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 werden die folgenden Verzeichnisse durchsucht:
./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 übernimmt keine lokal vorgenommenen Änderungen.
Wenn Sie die neuesten Projektübersetzungen bereits abgerufen haben und sie erneut herunterladen möchten, können Sie das Flag --force-download verwenden.
Die Verwendung von --force-download überschreibt alle lokal vorgenommenen Änderungen an den Übersetzungen und lädt die neuesten Übersetzungen herunter. Inhalte werden dabei nicht erneut übersetzt.
Wörterbuchdatei
Der Befehl translate erkennt die Wörterbuchdatei in Ihrem Projekt automatisch.
Standardmäßig sucht er nach einer Datei mit dem Namen dictionary.[json|ts|js] in den folgenden Verzeichnissen:
./src./
Sie können eine andere Wörterbuchdatei mit dem Flag --dictionary angeben oder die Eigenschaft dictionary in Ihrer Datei gt.config.json ändern.
Wie ist diese Anleitung?