# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: Connectez-vous et configurez vos projets depuis la CLI
URL: https://generaltranslation.com/fr/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Connectez-vous, configurez un projet et créez des clés aux permissions explicites depuis la CLI, ou lancez la configuration en mode headless depuis des scripts et des agents.
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

`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`](/docs/cli/reference/commands/init) pour configurer votre projet. La commande ne vous demande de vous connecter que si elle doit créer un projet ou une clé :

```bash
npx gt init
```

Utilisez [`gt login`](/docs/cli/reference/commands/login) pour vous connecter sans lancer la configuration, ou [`npx gt login --no-browser`](/docs/cli/reference/commands/login#flags) pour approuver la connexion depuis un autre appareil. Dans les deux cas, une approbation humaine est requise.

[`gt whoami`](/docs/cli/reference/commands/whoami) affiche l'identité avec laquelle vous êtes connecté, et [`gt logout`](/docs/cli/reference/commands/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`](/docs/cli/reference/commands/init#headless) liste les options manquantes avant de modifier le moindre fichier, et `--json` renvoie les événements de connexion, de transfert et de résultat :

```bash
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`](/docs/cli/reference/commands/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](/docs/react/nextjs/config#credentials)).

Utilisez [`gt api-key create`](/docs/cli/reference/commands/api-key-create) pour créer une clé de projet supplémentaire avec les permissions de votre choix :

```bash
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`](/docs/platform/core/reference/api-client#pagination) de [`generaltranslation/api`](/docs/platform/core/reference/api-client) pour parcourir tous les projets accessibles avec votre clé API, sans avoir à gérer les curseurs :

```ts
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`](/docs/platform/core/reference/api-client#api-error) dont le champ `code` contient le code d'état HTTP.

Les [utilitaires de polling du client d'API](/docs/platform/core/reference/api-client#job-polling) 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`](/docs/platform/core/reference/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`](/docs/cli/reference/commands/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`](/docs/platform/core/reference/api-client#job-polling) 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`](/docs/cli/reference/commands/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](/docs/cli/guides/configuring#credentials).
* **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`](/docs/platform/core/reference/gt-class-methods/translation/get-project-data) restent disponibles, mais sont dépréciées. Utilisez `apiKey` et privilégiez [`getProjectInfo`](/docs/platform/core/reference/gt-class-methods/project/project-management#get-project-info) 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`.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.