# General Translation Overview: Utiliser des agents IA de codage
URL: https://generaltranslation.com/fr/docs/overview/for-coding-agents.mdx
---

title: Utiliser des agents IA de codage
description: Comment utiliser des agents IA de codage et des LLMs avec General Translation en les orientant vers la documentation au format lisible par machine, le serveur MCP et notre guide d’agent clé en main.

---

General Translation est conçu pour fonctionner avec des agents IA de codage et des LLMs. Les bibliothèques sont open source, la configuration est prévisible et la documentation est publiée dans des formats lisibles par machine. Un agent comme Cursor, Claude Code ou Copilot peut ajouter et exécuter General Translation pour vous avec un contexte précis et à jour.

*Pour une localisation entièrement automatisée qui ouvre des pull requests de façon autonome, utilisez plutôt notre agent dédié [Locadex](/docs/platform/locadex/quickstart) au lieu de piloter votre propre agent.*

## Guide d’intégration rapide de l’agent [#agent-guide]

Donnez à votre agent tout ce dont il a besoin en un seul copier-coller. Copiez le guide ci-dessous dans un fichier `AGENTS.md` (ou `CLAUDE.md`, une règle Cursor ou le fichier d’instructions de votre outil) à la racine de votre projet, et votre agent ajoutera et exécutera correctement General Translation. Utilisez le bouton de copie en haut à droite du bloc.

````markdown title="AGENTS.md"
# General Translation — agent guide

Instructions pour les agents de codage IA qui ajoutent [General Translation](https://generaltranslation.com) à un projet. General Translation est un produit de localisation full-stack : des bibliothèques i18n open source et un CLI qui traduisent une application et son contenu dans n'importe quelle langue. Suivez ces règles lors de l'internationalisation du code ou de la mise en place des traductions.

## Que choisir

Choisissez le package correspondant à votre stack :

- **Next.js (App Router ou Pages Router)** → `gt-next`
- **React (SPA, par ex. Vite)** → `gt-react`
- **Serveur Node.js** → `gt-node`
- **Tout runtime JavaScript, ou contrôle de bas niveau** → `generaltranslation` (la bibliothèque Core)
- **Traduction de fichiers de contenu (JSON, MDX, YAML, et plus) ou exécution de traductions en CI** → le CLI `gt`

Tous ces outils sont gratuits et open source. Les bibliothèques fonctionnent avec ou sans compte General Translation ; une API Key déverrouille la traduction à la demande en développement ainsi que l'API de traduction hébergée.

## Configuration

Privilégiez l'assistant. Depuis la racine du projet, exécutez :

```bash
npx gt init
```

Il installe la bibliothèque appropriée et le CLI `gt`, configure le framework (pour Next.js, ajoute `withGTConfig` et GTProvider), crée gt.config.json et génère les identifiants API.

Pour une configuration manuelle, installez les packages vous-même :

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

Créez ensuite gt.config.json à la racine du projet — c'est la référence unique pour les paramètres régionaux :

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": { "gt": { "output": "public/_gt/[locale].json" } }
}
```

- `defaultLocale` — la langue dans laquelle le contenu source est rédigé.
- `locales` — les langues cibles de la traduction.
- `files.gt.output` — l'emplacement où le CLI écrit les fichiers de traduction (`[locale]` est remplacé par chaque langue). Ajoutez ce répertoire à `.gitignore` ; ces fichiers sont générés automatiquement.

Définissez les identifiants API en tant que variables d'environnement (dans `.env.local` pour Next.js, `.env` sinon) :

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

Ne commitez jamais `GT_API_KEY`, ne l'exposez pas au navigateur et ne le préfixez pas avec `NEXT_PUBLIC_`.

## Utilisation de base

Encapsulez le JSX visible par l'utilisateur dans `<T>`. Rédigez le contenu source directement — aucune clé de traduction n'est nécessaire :

```tsx
import { T } from 'gt-next'; // or 'gt-react'

// Tout ce qui se trouve dans <T> est traduit comme une unité
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Utilisez `useGT()` pour les chaînes autonomes (espaces réservés, `aria-label`, `alt`, libellés de boutons). `useGT()` retourne directement la fonction de traduction :

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ correct
// const { gt } = useGT(); // ❌ incorrect — useGT retourne la fonction, pas un objet

<input placeholder={gt('Search products')} />;
```

Dans les async App Router components, utilisez `getGT` à la place. `gt-next/server` ne fonctionne pas avec le Pages Router :

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

Encapsulez les valeurs dynamiques ou privées (noms, e-mails, identifiants) dans `<Var>` afin qu'elles ne soient pas traduites et ne soient jamais envoyées à l'API. Utilisez `<Currency>`, `<DateTime>` et `<Num>` pour les valeurs qui doivent être reformatées mais pas traduites :

```tsx
import { T, Var } from 'gt-next';

// Génère une seule traduction, conserve le nom inchangé
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

Pour les serveurs Node.js, initialisez une seule fois et résolvez les traductions par requête :

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// encapsulez les gestionnaires dans withGT(locale, ...) ; puis `const gt = await getGT()` à l'intérieur
```

Centralisez toute la configuration des paramètres régionaux dans gt.config.json — ne dispersez pas les listes de paramètres régionaux dans la base de code.

## Commandes

| Commande | Quand l'exécuter |
| --- | --- |
| `npx gt init` | Une seule fois, pour configurer un projet (installe les dépendances, configure le framework, crée gt.config.json, génère les identifiants). |
| `npx gt configure` | Pour créer ou mettre à jour gt.config.json (paramètres régionaux et fichiers) sans l'assistant complet. |
| `npx gt auth` | Pour générer ou renouveler les identifiants API. |
| `npx gt translate` | Pour traduire le projet via l'API General Translation. À exécuter en CI **avant** le build de production. |
| `npx gt generate` | Pour créer des modèles de fichiers de traduction à traduire manuellement (aucune API Key requise). |

Intégrez la traduction au build de production pour que les traductions restent à jour, par exemple : `"build": "npx gt translate && next build"`.

## Règles — à faire et à éviter

À faire :

- Encapsulez chaque nouveau contenu visible par l'utilisateur dans `<T>` (ou `useGT()`/`getGT()` pour les chaînes autonomes) au fur et à mesure que vous l'écrivez.
- Exécutez `npx gt translate` avant de committer ou de builder pour la production afin que le nouveau contenu soit traduit.
- Conservez la liste des paramètres régionaux uniquement dans gt.config.json.
- Encapsulez les valeurs dynamiques et privées dans `<Var>`, et ajoutez un `context` lorsqu'une chaîne est ambiguë.

À éviter :

- Coder en dur des chaînes déjà traduites dans le source, ou ajouter des branches `if`/`switch` par langue — traduisez plutôt le contenu source.
- Modifier manuellement les fichiers de traduction générés (le CLI les écrase).
- Committer `GT_API_KEY` ou l'exposer au client.
- Dupliquer la configuration des paramètres régionaux en dehors de gt.config.json.

## Liens

- [`llms.txt`](/llms.txt) — index de documentation concis et lisible par machine.
- [`sitemap.md`](/sitemap.md) — carte de toutes les pages de documentation.
- Quickstarts : [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [Bibliothèque Core](/docs/platform/core/quickstart), et le [CLI](/docs/cli/quickstart).
- [Concepts clés](/docs/overview/key-concepts) — paramètres régionaux, contexte, et contenu statique vs. dynamique.
````

## Orientez les agents vers la documentation [#point-agents]

Donnez à votre agent un accès direct à la documentation afin que ses réponses restent exactes. General Translation publie plusieurs points d’entrée exploitables par machine à la racine du site :

* [`llms.txt`](/llms.txt) — un index court de la documentation, au format [llmstxt.org](https://llmstxt.org/).
* [`sitemap.md`](/sitemap.md) — une carte liée de toutes les pages, dans l’ordre de navigation.

Chaque page de documentation est également disponible en **Markdown brut** : ajoutez `.md` à n’importe quelle URL de page (par exemple, `/docs/cli/quickstart.md`) pour récupérer la source brute plutôt que d’analyser le HTML affiché.

Pour ajouter la documentation comme contexte, collez une URL de la documentation ou le lien `llms.txt` dans le contexte de votre agent, ou ajoutez la documentation comme source dans les outils qui prennent en charge l’indexation de la documentation.

## Serveur MCP [#mcp]

General Translation propose un serveur [Model Context Protocol](https://modelcontextprotocol.io) (MCP) qui permet aux agents d’interroger directement la documentation. Il se présente sous deux formes :

* **Local (stdio)** — le package npm publié [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp), exécuté sur votre machine avec `npx`. Idéal pour les outils qui maintiennent une connexion persistante, comme Cursor et Claude Code.
* **Distant (HTTP/SSE)** — un point de terminaison hébergé à l’adresse `https://mcp.gtx.dev`. Utilisez le point de terminaison SSE uniquement si votre outil ne prend pas en charge le HTTP en streaming.

Configurez la connexion avec le transport pris en charge par votre outil. Le format de configuration est identique d’un outil à l’autre : ajoutez-le au fichier de configuration MCP de votre outil (par exemple, `.mcp.json`) :

<Tabs items={['Local', 'HTTP en streaming', 'SSE']}>
  <Tab value="Local">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="HTTP en streaming">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Une fois la connexion établie, demandez à votre agent d’utiliser le serveur MCP `generaltranslation`. *Exemple : &quot;Utilise le serveur MCP generaltranslation pour expliquer comment utiliser un composant [`<T>`](/docs/react/reference/components/t).&quot;*

## Conseils spécifiques aux éditeurs [#editor-tips]

L’essentiel de la configuration est le même d’un agent à l’autre ; voici les quelques points où les consignes diffèrent.

* **Cursor** — enregistrez le serveur MCP, puis demandez-lui d’« utiliser l’outil `generaltranslation` ». Ajoutez la Documentation comme source, ou faites référence à `/llms.txt` dans votre prompt.
* **Claude Code** — lit automatiquement un `AGENTS.md` à la racine ; il suffit donc d’ajouter le [guide d’intégration rapide de l’agent](#agent-guide) au `AGENTS.md` de votre projet pour le préparer. Enregistrez le serveur MCP et demandez-lui d’« utiliser le serveur MCP `generaltranslation` ».
* **Copilot** — placez les consignes à l’échelle du repo dans votre fichier d’instructions (par exemple, `.github/copilot-instructions.md`) et faites référence à `/llms.txt` de la Documentation à cet endroit.

## Bonnes pratiques [#best-practices]

Les agents sont fiables pour les tâches d’i18n mécaniques, mais la qualité de la traduction et la configuration nécessitent toujours une intervention humaine. Répartissez le travail ainsi :

* **Confier à l’agent :** envelopper les textes destinés à l’utilisateur dans `<T>`, ajouter [`useGT()`](/docs/react/reference/hooks/use-gt) pour les chaînes autonomes, générer le squelette de `gt.config.json` et exécuter `npx gt init`.
* **Vérifier manuellement :** le [contexte de traduction](/docs/overview/key-concepts#context) (glossaire et directives) que l’agent génère, la configuration des paramètres régionaux (`defaultLocale` et `locales`), et que les valeurs dynamiques ou privées sont enveloppées dans [`<Var>`](/docs/react/reference/components/var).
* **Ne jamais laisser l’agent faire :** modifier manuellement les fichiers de traduction générés, ni coder en dur des chaînes déjà traduites au lieu de traduire le texte source avec la CLI.