Traduire
Comment traduire votre projet
Utilisation
Exécutez ceci dans votre pipeline CI avant de construire votre application Next.js pour la production.
Remarque : Cette commande nécessite une clé API de production ! Obtenez-en une sur la plateforme.
Aperçu
La commande gtx-cli translate traduit votre projet. Elle parcourt l'arborescence des fichiers de votre projet et traduit tout contenu enveloppé dans un composant <T>.
De plus, elle inclut le contenu du fichier dictionnaire (si un fichier est fourni).
Cette commande est le principal moyen d'utiliser l'API General Translation et les services associés.
Pour utilisation en production uniquement !
Cette commande est destinée aux builds de production et ne doit pas être utilisée en développement.
Avant d'exécuter cette commande, assurez-vous d'être sur la branche qui sera utilisée pour la production.
N'oubliez pas également de spécifier votre clé API de production (GT_API_KEY) et votre ID de projet (GT_PROJECT_ID) dans vos variables d'environnement.
Utilisation
Il existe quatre façons d'utiliser la commande translate. Les méthodes 2, 3 et 4 nécessitent une clé API de production :
Nous recommandons d'exécuter npx gtx-cli init pour configurer d'abord votre projet avant d'exécuter la commande translate.
Selon la configuration de votre projet, le comportement de la commande translate peut changer.
Méthode 1 : Traduire les fichiers JSON de votre projet.
Si vous utilisez d'autres bibliothèques i18n comme next-intl, react-i18next, ou next-i18next, vous pouvez utiliser cette méthode pour traduire les fichiers JSON de votre projet.
Les traductions seront automatiquement enregistrées dans votre base de code, ainsi que publiées sur le CDN GT si vous le souhaitez.
Lors de l'exécution de npx gtx-cli init, spécifiez que vous utilisez une bibliothèque i18n tierce avant d'exécuter la commande translate.
Consultez la documentation de configuration CLI pour plus de détails.
L'outil CLI détectera automatiquement votre bibliothèque i18n en lisant votre fichier package.json, et traduira votre contenu tout en respectant la syntaxe de votre bibliothèque i18n.
Méthode 2 : Traduire votre projet et enregistrer les traductions sur le CDN GT.
Si vous utilisez gt-next ou gt-react, vous pouvez utiliser cette méthode pour traduire votre projet.
Lors de l'exécution de npx gtx-cli init, si vous sélectionnez l'option pour enregistrer les traductions à distance, la commande translate enregistrera les traductions sur le CDN GT.
Méthode 3 : Traduire votre projet et enregistrer les traductions dans votre base de code.
Lors de l'exécution de npx gtx-cli init, si vous sélectionnez l'option pour enregistrer les traductions localement, la commande translate enregistrera les traductions dans votre base de code.
gt-next et gt-react peuvent ensuite servir ces traductions locales à vos utilisateurs, plutôt que d'utiliser le CDN public de General Translation.
Cette méthode est utile si vous utilisez un système de gestion de contenu personnalisé, ou si vous ne souhaitez pas utiliser le CDN GT.
Méthode 4 : Valider les composants <T> et le fichier dictionnaire de votre projet.
Cette méthode est utile pour valider les composants <T> et le fichier dictionnaire de votre projet.
Cela garantit que votre projet est correctement configuré et que les traductions seront valides et précises.
Aucune traduction ne sera générée si l'option --dry-run est fournie.
Drapeaux
| Paramètre | Description | Type | Optionnel | Par défaut |
|---|---|---|---|---|
--api-key | Spécifier une clé API de production | string | true | |
--project-id | Spécifier l'ID du projet | string | true | |
--version-id | Spécifier un ID de version (par défaut, un hash du contenu) | string | true | |
--config <path> | Spécifier un chemin vers le fichier de configuration GT | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Spécifier un chemin vers le fichier de configuration TS ou JS | string | true | |
--src <paths> | Spécifier le(s) répertoire(s) source à scanner | [string] | true | ./src && ./app && ./pages && ./components |
--dictionary <path> | Spécifier un chemin vers le fichier dictionnaire | string | true | |
--inline | Inclure les balises <T> en ligne en plus du dictionnaire | boolean | true | true |
--timeout | Le délai d'attente pour la demande de traduction en secondes | number | true | 600 |
--new, --locales <locales> | Locales dans lesquelles traduire votre projet | [string] | true | |
--default-locale <locale> | La locale source pour le projet | string | true | en |
--ignore-errors | Ignorer les erreurs et forcer la traduction pour le contenu valide | flag | true | false |
--dry-run | Exécuter la commande en mode simulation | flag | true | false |
--no-wait | Ne pas attendre que les traductions soient terminées avant de quitter | flag | true | false |
--publish | Publier les traductions sur le CDN | flag | true | false |
Tous ces paramètres sont optionnels et peuvent être fournis alternativement dans le fichier gt.config.json.
N'ajoutez pas votre clé API au fichier gt.config.json !
Vous devriez plutôt la définir comme variable d'environnement. Le CLI lira automatiquement GT_API_KEY s'il est défini.
Voici quelques paramètres clés :
| Paramètre | Description |
|---|---|
--dry-run | Ce drapeau fera que le CLI analysera et validera votre projet, mais ne communiquera pas avec l'API GT. C'est utile pour valider votre base de code. |
--api-key | À moins que vous n'utilisiez --dry-run, vous devez fournir une clé API de production. |
--project-id | De même, à moins que vous n'utilisiez --dry-run, vous devez fournir un ID de projet. |
--publish | Si vous utilisez des traductions locales et souhaitez rendre vos traductions publiquement disponibles sur le CDN GT, vous pouvez utiliser ce drapeau. |
--new, --locales <locales> | Locales dans lesquelles traduire votre projet. Celles-ci seront ajoutées aux locales spécifiées dans votre fichier gt.config.json. |
Fichier de configuration
Lors de la première exécution de l'outil CLI, il tentera de créer un fichier gt.config.json à la racine de votre projet.
Ce fichier contient des métadonnées sur votre projet qui sont utilisées pour traduire votre contenu.
En savoir plus sur le fichier gt.config.json ici.