Traduction
Comment traduire votre projet
Utilisation
Exécutez cette commande dans votre pipeline CI avant de générer votre application pour la production.
npx gtx-cli translateRemarque : Cette commande nécessite une clé d’API de production ! Procurez-vous-en une sur la plateforme.
Vue d’ensemble
La commande gtx-cli translate traduit votre projet.
Elle parcourt l’arborescence de fichiers de votre projet et traduit tout contenu enveloppé dans un composant <T> ou utilisant les fonctions useGT.
Elle inclut également le contenu du fichier dictionary (s’il est fourni).
Cette commande est le moyen principal d’utiliser la General Translation API et les services associés.
Réservé à la production !
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 déployée en production.
N’oubliez pas non plus de renseigner votre clé d’API de production (GT_API_KEY) et votre Project ID (GT_PROJECT_ID) dans vos variables d’environnement.
Utilisation
Il existe 3 façons d’utiliser la commande translate. Les méthodes 1 et 2 nécessitent une clé d’API de production :
Nous vous recommandons d’exécuter l’assistant de configuration : npx gtx-cli configure afin de préparer votre projet avant d’exécuter la commande translate.
En fonction de la configuration de votre projet, le comportement de la commande translate peut varier.
Méthode 1 : Traduire les fichiers JSON de votre projet.
Si vous utilisez d’autres bibliothèques d’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 codebase.
Pour utiliser le CLI afin de traduire les fichiers JSON de votre projet, modifiez votre fichier gt.config.json pour inclure json dans la propriété files.
Consultez la documentation de configuration du CLI pour plus de détails.
npx gtx-cli translateL’outil CLI détectera automatiquement votre bibliothèque i18n en lisant votre fichier package.json et traduira vos fichiers JSON tout en respectant la syntaxe propre à votre bibliothèque i18n.
Méthode 2 : Traduire votre projet GT
Si votre projet utilise gt-next ou gt-react, vous pouvez utiliser cette méthode pour générer les traductions de votre projet.
npx gtx-cli translatePar défaut, les traductions sont enregistrées sur le GT CDN.
Cependant, si vous souhaitez enregistrer les traductions dans votre codebase, ajoutez la propriété gt à l’objet files dans le fichier gt.config.json.
gt-next et gt-react prennent en charge la mise à disposition des traductions en local, ainsi que l’utilisation du CDN public de General Translation.
Nous recommandons d’utiliser le CDN pour réduire la latence, améliorer les performances et diminuer la taille des bundles.
Consultez la documentation de configuration du CLI pour plus de détails.
Méthode 3 : Valider les composants <T> et le fichier dictionary de votre projet.
Cette méthode est utile pour valider les composants <T> et le fichier dictionary de votre projet.
Cela garantit que votre projet est correctement configuré et que les traductions seront valides et exactes.
Aucune traduction ne sera générée si l’option --dry-run est utilisée.
npx gtx-cli translate --dry-runOptions
| Parameter | Description | Type | Optional | Default |
|---|---|---|---|---|
--api-key | Spécifie une clé d’API de production | string | true | |
--project-id | Spécifie l’ID du projet | string | true | |
--version-id | Spécifie un ID de version (par défaut, un hash du contenu) | string | true | |
--config <path> | Spécifie le chemin du fichier de configuration GT | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Spécifie le chemin du fichier de configuration TS ou JS | string | true | |
--src <paths> | Liste d’expressions globales (globs) séparées par des espaces pour faire correspondre les fichiers source. Doit être relative au répertoire racine. | [string] | true | [ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ] |
--dictionary <path> | Spécifie le chemin du fichier dictionary | string | true | |
--inline | Inclure les balises <T> en ligne en plus du dictionary | boolean | true | true |
--timeout | Délai d’attente de la requête de traduction, en secondes | number | true | 600 |
--new, --locales <locales> | Locales vers lesquelles traduire votre projet | [string] | true | |
--default-locale <locale> | La locale source du projet | string | true | en |
--ignore-errors | Ignorer les erreurs et forcer la traduction du contenu valide | flag | true | false |
--dry-run | Exécuter la commande à blanc | flag | true | false |
--force | Forcer une retraduction de votre projet | flag | true | false |
--force-download | Forcer le téléchargement de toutes les traductions du projet | flag | true | false |
Tous ces paramètres sont facultatifs.
N’ajoutez pas votre clé d’API dans le fichier gt.config.json !
Définissez-la plutôt comme variable d’environnement. La CLI lira automatiquement GT_API_KEY si elle est définie.
Voici quelques paramètres importants :
| Parameter | Description |
|---|---|
--dry-run | Cette option amène la CLI à analyser et valider votre projet sans communiquer avec l’API de GT. Utile pour valider votre codebase. |
--api-key | À moins d’utiliser --dry-run, vous devez fournir une clé d’API de production. |
--project-id | De même, à moins d’utiliser --dry-run, vous devez fournir un ID de projet. |
--new, --locales <locales> | Locales vers lesquelles traduire votre projet. Elles seront ajoutées aux locales spécifiées dans votre fichier gt.config.json. |
--force | Cette option force une retraduction de votre projet et écrase toutes les traductions existantes. |
--force-download | Cette option force le téléchargement de toutes les traductions et écrase toutes les modifications que vous avez apportées localement. |
Fichier de configuration
Lors de la première exécution de l’outil CLI, celui-ci tentera de créer un fichier gt.config.json à la racine de votre projet.
Ce fichier contient des métadonnées sur votre projet utilisées pour traduire votre contenu.
En savoir plus sur le fichier gt.config.json ici.
Conseils essentiels
Sources de contenu
La commande translate recherche de manière récursive le contenu traduisible dans votre projet.
Par défaut, elle parcourt les répertoires suivants :
./src./app./pages./components
Vous pouvez spécifier d’autres répertoires à analyser avec l’option --src,
ou modifier la propriété src dans votre fichier gt.config.json.
Écrasement des traductions
Par défaut, l’outil CLI n’écrase pas les modifications que vous avez apportées aux traductions en local, sauf si le contenu source a changé.
Si vous souhaitez retraduire du contenu de projet déjà traduit, vous pouvez utiliser l’option --force.
L’utilisation de --force écrasera toutes les traductions existantes et ne conservera aucune des modifications que vous avez apportées en local.
Si vous avez déjà récupéré les traductions les plus récentes du projet et souhaitez les télécharger à nouveau, vous pouvez utiliser l’option --force-download.
L’utilisation de --force-download écrasera les modifications que vous avez apportées en local et récupérera les traductions les plus récentes. Aucun contenu ne sera retraduit.
Fichier dictionary
La commande translate détecte automatiquement le fichier dictionary dans votre projet.
Par défaut, elle recherche un fichier nommé dictionary.[json|ts|js] dans les répertoires suivants :
./src./
Vous pouvez indiquer un autre fichier dictionary avec l’option --dictionary, ou modifier la propriété dictionary dans votre fichier gt.config.json.
Que pensez-vous de ce guide ?