# 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 for AI coding agents adding [General Translation](https://generaltranslation.com) to a project. General Translation is a full-stack localization product: open-source i18n libraries plus a CLI that translate an app and its content into any language. Follow these rules when internationalizing code or wiring up translations.

## What to use

Pick the package that matches the stack:

- **Next.js (App Router or Pages Router)** → `gt-next`
- **React (SPA, e.g. Vite)** → `gt-react`
- **Node.js server** → `gt-node`
- **Any JavaScript runtime, or lower-level control** → `generaltranslation` (the Core library)
- **Translating content files (JSON, MDX, YAML, and more) or running translation in CI** → the `gt` CLI

All of these are free and open-source. The libraries work with or without a General Translation account; an API key unlocks on-demand translation in development and the hosted translation API.

## Setup

Prefer the wizard. From the project root, run:

```bash
npx gt init
```

It installs the right library and the `gt` CLI, wires up the framework (for Next.js, adds `withGTConfig` and `GTProvider`), creates `gt.config.json`, and generates API credentials.

For manual setup, install the packages yourself:

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

Then create `gt.config.json` in the project root — this is the single source of truth for locales:

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

- `defaultLocale` — the language the source is written in.
- `locales` — the languages to translate into.
- `files.gt.output` — where the CLI writes translation files (`[locale]` is replaced per language). Add this directory to `.gitignore`; the files are generated.

Set API credentials as environment variables (in `.env.local` for Next.js, `.env` otherwise):

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

Never commit `GT_API_KEY`, expose it to the browser, or prefix it with `NEXT_PUBLIC_`.

## Core usage

Wrap user-facing JSX in `<T>`. Write source copy directly — no translation keys needed:

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

// Everything inside <T> is translated as a unit
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Use `useGT()` for standalone strings (placeholders, `aria-label`, `alt`, button labels). `useGT()` returns the translation function directly:

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

const gt = useGT(); // ✅ correct
// const { gt } = useGT(); // ❌ wrong — useGT returns the function, not an object

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

In async App Router components, use `getGT` instead. `gt-next/server` does not work with the Pages Router:

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

const gt = await getGT();
```

Wrap dynamic or private values (names, emails, IDs) in `<Var>` so they are not translated and never sent to the API. Use `<Currency>`, `<DateTime>`, and `<Num>` for values that should be reformatted but not translated:

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

// Generates one translation, keeps the name unchanged
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

For Node.js servers, initialize once and resolve translations per request:

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

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// wrap handlers in withGT(locale, ...); then `const gt = await getGT()` inside them
```

Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase.

## Commands

| Command | When to run |
| --- | --- |
| `npx gt init` | Once, to set up a project (installs deps, configures the framework, creates `gt.config.json`, generates credentials). |
| `npx gt configure` | To create or update `gt.config.json` (locales and files) without the full wizard. |
| `npx gt auth` | To generate or refresh API credentials. |
| `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production. |
| `npx gt generate` | To create translation file templates to translate manually (no API key needed). |

Add translation to the production build so translations stay current, for example: `"build": "npx gt translate && next build"`.

## Rules — do and don't

Do:

- Wrap every new piece of user-facing copy in `<T>` (or `useGT()`/`getGT()` for standalone strings) as you write it.
- Run `npx gt translate` before committing or building for production so new copy is translated.
- Keep the locale list in `gt.config.json` only.
- Wrap dynamic and private values in `<Var>`, and add `context` when a string is ambiguous.

Don't:

- Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead.
- Hand-edit generated translation files (the CLI overwrites them).
- Commit `GT_API_KEY` or expose it to the client.
- Duplicate the locale configuration outside `gt.config.json`.

## Links

- [`llms.txt`](/llms.txt) — index de documentation concis et lisible par machine.
- [`llms-full.txt`](/llms-full.txt) — contenu complet de la documentation pour les outils capables de charger un contexte plus large.
- [`sitemap.xml`](/sitemap.xml) — carte de toutes les pages publiées.
- 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 lisibles par machine à la racine du site et sous `/docs` sur l’hôte de la documentation :

* [`llms.txt`](/llms.txt) — un index court de la documentation, au format [llmstxt.org](https://llmstxt.org/).
* [`llms-full.txt`](/llms-full.txt) — le contenu complet de la documentation dans un seul fichier, à l’exclusion de la référence OpenAPI générée.
* [`sitemap.xml`](/sitemap.xml) — une carte lisible par machine de chaque page publiée.

L’hôte de la documentation sert également ces fichiers à `/docs/llms.txt` et `/docs/llms-full.txt`. Chaque page de documentation est également disponible en **Markdown brut** : ajoutez `.md` ou `.mdx` à n’importe quelle URL de page (par exemple, `/docs/cli/quickstart.mdx`) 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>`](/docs/react/reference/components/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`](/docs/cli/reference/commands/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.