Traduire
Comment traduire votre projet
Utilisation
Exécutez cette commande dans votre pipeline CI avant de construire votre application pour la production.
npx gtx-cli translateRemarque : Cette commande nécessite une clé d’API de production ! Obtenez-en une sur la plateforme.
Présentation
La commande gtx-cli translate traduit votre projet.
Elle parcourt l’arborescence 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 principal moyen d’utiliser la General Translation API et les services associés.
À utiliser uniquement en 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 utilisée pour la production.
N’oubliez pas non plus de définir votre clé d’API de production (GT_API_KEY) et votre ID de projet (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.
Selon 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 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.
Pour utiliser l’outil 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 de la 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 CDN (réseau de distribution de contenu) de GT.
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 de la CLI pour en savoir plus.
Méthode 3 : Validez 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écifier une clé d’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 le chemin du fichier de configuration GT | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Spécifier le chemin du fichier de configuration TS ou JS | string | true | |
--src <paths> | Liste d’expressions glob séparées par des espaces pour faire correspondre les files 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écifier le chemin du fichier dictionary | string | true | |
--inline | Inclure les balises <T> inline 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 Error 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 optionnels.
N’ajoutez pas votre clé d’API dans le fichier gt.config.json !
Vous devriez plutôt la définir comme variable d’environnement. La CLI lira automatiquement GT_API_KEY si elle est définie.
Voici quelques paramètres clés :
| Parameter | Description |
|---|---|
--dry-run | Ce flag amène la CLI à analyser et valider votre projet, sans communiquer avec l’API 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 | Ce flag forcera une retraduction de votre projet et écrasera toutes les traductions existantes. |
--force-download | Ce flag forcera le téléchargement de toutes les traductions et écrasera les modifications que vous avez effectuées localement. |
Fichier de configuration
Lors de la première exécution de la CLI, un fichier gt.config.json sera créé à la racine de votre projet.
Ce fichier contient des métadonnées sur votre projet utilisées pour traduire votre contenu.
Pour en savoir plus sur le fichier gt.config.json, consultez cette page.
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 en modifiant 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 localement aux traductions, 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 effectuées localement.
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 effectuées localement et récupérera les traductions les plus récentes. Cela ne retraduit aucun contenu.
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 spécifier un autre fichier dictionary en utilisant l’option --dictionary, ou en modifiant la propriété dictionary dans votre fichier gt.config.json.
Comment trouvez-vous ce guide ?