Guide d’utilisation
Guide d’utilisation de l’outil en ligne de commande GT
Aperçu
Ce guide vous accompagnera pas à pas dans l’utilisation de l’outil CLI de General Translation (gtx-cli) pour traduire votre projet.
L’outil CLI est compatible avec n’importe quelle bibliothèque i18n, que vous utilisiez gt-next, gt-react ou des bibliothèques tierces comme next-intl ou react-i18next.
L’outil CLI a pour rôle de connecter votre projet au service de traduction par IA de General Translation.
Il existe plusieurs manières d’utiliser l’outil CLI. Veuillez consulter la section correspondant à votre cas d’usage.
Installation
Pour installer l’outil en ligne de commande (CLI), exécutez la commande suivante :
npm i gtx-cliyarn add --dev gtx-clibun add --dev gtx-clipnpm add --save-dev gtx-cliCas d’usage
Traduction des projets GT
L’outil CLI peut être utilisé pour traduire vos projets qui utilisent gt-next ou gt-react.
Ce guide part du principe que vous avez déjà configuré votre base de code pour utiliser gt-next ou gt-react, conformément aux tutoriels gt-next et gt-react.
- D’abord, vous devez configurer les paramètres GT de votre projet.
npx gtx-cli configureCette commande générera automatiquement une clé d’API et un ID de projet pour votre projet via le tableau de bord.
Toutefois, si vous préférez définir manuellement la clé d’API et l’ID de projet, suivez les étapes 2 et 3 ci-dessous.
- Ensuite, vous devez créer un projet dans le tableau de bord General Translation.
Après avoir créé un projet, vous devez générer une clé d’API de production. Accédez à la page « API Keys » et cliquez sur le bouton « Create API Key ».
- Ensuite, ajoutez votre clé d’API et votre ID de projet à vos variables d’environnement.
GT_API_KEY=<votre-clé-api>
GT_PROJECT_ID=<votre-id-projet>- Enfin, exécutez la commande de traduction.
npx gtx-cli translatePar défaut, l’outil CLI publie les traductions sur le CDN de General Translation, afin qu’elles soient prêtes à être utilisées dans votre projet.
Si vous souhaitez désactiver ce comportement (par exemple, si vous chargez les traductions depuis une autre source), désactivez le paramètre CDN dans les paramètres de projet du tableau de bord.
Consultez la Référence de l’API pour en savoir plus sur la commande translate.
Traduction des fichiers de langue (bibliothèques i18n tierces ou projets GT autonomes)
L’outil CLI vous permet de traduire des fichiers de langue pour des bibliothèques i18n tierces ou avec une implémentation autonome de gt-next ou de gt-react.
La plupart des bibliothèques i18n s’appuient sur des fichiers JSON pour stocker les données de traduction. L’outil CLI peut automatiquement traduire ces fichiers JSON dans les langues de votre choix.
- Commencez par configurer les paramètres GT de votre projet.
npx gtx-cli configureCette commande crée un fichier gt.config.json à la racine de votre projet, avec quelques paramètres de configuration de base, comme la locale par défaut de votre projet et les locales prises en charge.
Cette commande génère automatiquement une clé d’API et un ID de projet pour votre projet via le tableau de bord.
Toutefois, si vous souhaitez définir manuellement la clé d’API et l’ID de projet, suivez les étapes 2 et 3 ci-dessous.
- Ensuite, vous devez créer un projet dans le tableau de bord General Translation.
Après avoir créé un projet, vous devez générer une clé d’API de production. Accédez à la page « API Keys » et cliquez sur le bouton « Create API Key ».
- Ajoutez ensuite votre clé d’API et l’ID de projet à vos variables d’environnement.
GT_API_KEY=<votre-clé-api>
GT_PROJECT_ID=<votre-id-projet>- Enfin, exécutez la commande de traduction.
npx gtx-cli translatePar défaut, l’outil CLI recherche les fichiers à traduire d’après la propriété files de votre fichier gt.config.json.
Il utilise la valeur de defaultLocale indiquée dans votre gt.config.json comme langue source.
Les fichiers traduits sont enregistrés à l’emplacement de sortie correspondant défini dans votre gt.config.json.
Consultez la documentation de configuration pour plus d’informations sur la propriété files.
Génération de fichiers de langue pour les projets GT
L’outil CLI peut être utilisé pour générer des fichiers de langue pour les projets qui utilisent gt-next ou gt-react.
Ce cas d’usage est utile si vous souhaitez utiliser votre propre prestataire de traduction.
Contrairement à d’autres bibliothèques d’i18n, gt-next et gt-react prennent en charge les traductions en ligne, ce qui signifie qu’il n’y a pas de structure de fichiers JSON traditionnelle avec des clés et des valeurs pour chaque langue.
Ainsi, pour suivre l’évolution des textes, les bibliothèques GT stockent les empreintes (hashes) du texte original dans le code source.
Cette structure de données interne (basée sur des hashes) est peu pratique à manipuler ; l’outil CLI fournit donc une commande pratique pour générer des fichiers de langue pour votre projet.
- Tout d’abord, vous devez configurer les paramètres GT de votre projet.
npx gtx-cli configureLorsqu’il vous est demandé si vous souhaitez enregistrer les traductions sur le GT CDN, sélectionnez l’option « Non ».
- Exécutez :
npx gtx-cli generateCette commande génère un fichier source pour votre locale par défaut, ainsi que pour toutes les autres locales configurées pour votre projet.
Le contenu de chaque fichier est identique et sera fusionné avec les traductions existantes de votre projet.
Consultez la Référence de l’API pour plus d’informations sur la commande generate.
Notes
gtx-cli translatepermet de générer automatiquement les traductions de votre projet.- Si vous utilisez une bibliothèque i18n tierce, vous pouvez mettre à jour automatiquement tous vos fichiers JSON de traduction à chaque modification de votre projet. Ajoutez simplement la commande
gtx-cli translateà votre processus de build ou à votre processus de CD (Continuous Delivery/Déploiement continu) avant la commande de build pour ajouter automatiquement les traductions à votre projet.
Prochaines étapes
- Consultez la Référence de l’API du CLI pour en savoir plus.
Que pensez-vous de ce guide ?