gt@2.23.0 / @generaltranslation/api@0.5.0

gt@2.23.0 intègre au terminal la connexion au compte, la sélection de projet, la création de clés à portée restreinte et une configuration scriptable. Les versions @generaltranslation/api@0.5.0 et generaltranslation@9.5.2 publiées en parallèle ajoutent la découverte de projets avec pagination automatique.

Démarrer avec la configuration guidée

Exécutez gt init pour configurer votre projet. La commande ne vous demande de vous connecter que si elle doit créer un projet ou une clé :

npx gt init

Utilisez gt login pour vous connecter sans lancer la configuration, ou npx gt login --no-browser pour approuver la connexion depuis un autre appareil. Dans les deux cas, une approbation humaine est requise.

gt whoami affiche l'identité avec laquelle vous êtes connecté, et gt logout supprime la connexion enregistrée. Pour les workflows automatisés, utilisez des clés API à portée restreinte, stockées dans le gestionnaire de secrets de votre fournisseur de CI.

Exécuter la configuration depuis des scripts et des agents

Chaque question de configuration a son option équivalente. En l'absence de terminal, ou avec --no-interactive, gt init liste les options manquantes avant de modifier le moindre fichier, et --json renvoie les événements de connexion, de transfert et de résultat :

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults accepte les choix locaux recommandés, mais ne crée jamais de projets ni de clés.

Choisir un projet et les permissions de la clé

gt init peut sélectionner un projet auquel vous avez accès ou en créer un dans une organisation où vous disposez des permissions nécessaires, puis enregistrer son ID ainsi qu’une clé d’exécution de développement dans .env.local.

La clé n’accorde que project:translations:generate : elle sert aux traductions à l’exécution en local, et non aux imports via la CLI ni à la CI. Les valeurs GT_API_KEY existantes ne sont pas modifiées. Les projets Next.js utilisant l’App Router reçoivent NEXT_PUBLIC_GT_PROJECT_ID et NEXT_PUBLIC_GT_DEV_API_KEY, ce qui permet de traduire également les client components en développement ; veillez à exclure ces deux variables des builds de production (voir identifiants Next.js).

Utilisez gt api-key create pour créer une clé de projet supplémentaire avec les permissions de votre choix :

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

Vous devez disposer de l'autorisation de créer des clés et d'accorder chacune des permissions sélectionnées. La commande n'affiche le secret qu'une seule fois ; conservez-le en lieu sûr. Pour la CI, choisissez les permissions nécessaires à l'ensemble du workflow au lieu de réutiliser cet exemple limité à la génération. N'incluez jamais de clés API dans les bundles déployés sur navigateur ou sur mobile.

Utiliser des appels d'API typés et vérifier les résultats des tâches

Utilisez paginate de generaltranslation/api pour parcourir tous les projets accessibles avec votre clé API, sans avoir à gérer les curseurs :

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

Avec un client createApiClient, les échecs HTTP dans les appels throwOnError lèvent désormais une ApiError dont le champ code contient le code d'état HTTP.

Les utilitaires de polling du client d'API vous permettent d'attendre la fin des tâches de traduction et renvoient complete: false en cas de dépassement du délai. Une tâche terminée n'est pas forcément une tâche réussie : vérifiez les résultats des tâches avant de télécharger les traductions.

Le formatage des diagnostics est désormais disponible via le point d'entrée public generaltranslation/diagnostics. Les outils peuvent ainsi formater des messages exploitables sans importer l'intégralité du point d'entrée Core.

Mise à niveau

Effectuez la mise à niveau pour lister les projets et les organisations. L’API les renvoie désormais dans items au lieu de projects ou orgs, et rejette les curseurs émis avant ce changement. Les versions antérieures de la CLI ne peuvent pas les lister dans gt init. Les appels HTTP directs et via le SDK doivent lire items et reprendre la pagination depuis le début.
Interceptez ApiError dans les appels qui lèvent des exceptions. Les échecs HTTP dans les appels throwOnError et dans awaitJobs lèvent ApiError au lieu du body de réponse décodé. Les appels sans throwOnError renvoient toujours le body dans error.
Déplacez src/gt.config.json. La CLI ne lit plus ce fichier. Déplacez-le à la racine du projet ou passez --config src/gt.config.json.
Remplacez gt auth et --key-type. Utilisez login pour l’authentification du compte, init pour la configuration guidée du projet, et la création explicite de clés pour obtenir des identifiants supplémentaires. gt configure n’est pas un substitut sans effets de bord : selon votre configuration, cette commande peut installer des dépendances et provisionner des identifiants.
Séparez les identifiants d’exécution et ceux des outils. GT_DEV_API_KEY reste un paramètre d’exécution du framework. Se connecter ne suffit pas à configurer les identifiants du SDK à l’exécution. Les clés API explicites restent prioritaires sur la connexion enregistrée par la CLI ; consultez la sélection des identifiants.
Vérifiez vos hypothèses sur les nouvelles tentatives. Les requêtes POST de gestion ne sont pas automatiquement relancées en cas d’échec réseau ou serveur, mais les réponses 429 peuvent encore l’être lorsque les nouvelles tentatives sont activées. La traduction à l’exécution de Core ne relance automatiquement ni ces échecs ni les réponses 429. Évitez de relancer aveuglément la création de projets ou de clés : chaque requête réussie crée une nouvelle ressource.
Conservez les API de compatibilité prises en charge. La solution de repli devApiKey de Core et getProjectData restent disponibles, mais sont dépréciées. Utilisez apiKey et privilégiez getProjectInfo pour les nouveaux appels récupérant les informations de projet.
Tenez compte des changements de validation et de résultats. Les valeurs de fournisseur de modèle non prises en charge échouent avant même l’envoi de la requête. Les résultats d’envoi de polices n’incluent plus le champ deduped.