# General Translation Overview: Utiliser des agents IA de codage URL: https://generaltranslation.com/fr/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt 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’intégration rapide de l’agent. 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, ou récupérez le même guide directement depuis [`/AGENTS.md`](/AGENTS.md). ````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` - **Vue 3** → `gt-vue` - **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 ``. Write source copy directly — no translation keys needed: ```tsx import { T } from 'gt-next'; // or 'gt-react' // Everything inside is translated as a unit

Welcome to my app

; ``` 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 ; ``` 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 `` so they are not translated and never sent to the API. Use ``, ``, and `` for values that should be reformatted but not translated: ```tsx import { T, Var } from 'gt-next'; // Generates one translation, keeps the name unchanged Hello, {name}! ; ``` 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'] }); // encapsulez les handlers dans withGT(locale, ...) ; puis `const gt = await getGT()` à l'intérieur ``` Conservez toute la configuration des paramètres régionaux dans `gt.config.json` — ne dispersez pas les listes de locales dans le code. ## Commandes | Commande | Quand l'exécuter | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx gt init` | Une 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` (locales et fichiers) sans l'assistant complet. | | `npx gt auth` | Pour générer ou renouveler les identifiants d'API. | | `npx gt translate` | Pour traduire le projet via l'API General Translation. À exécuter en CI **avant** la compilation pour la production ; ajoutez `--save-local` uniquement lorsque les modifications locales doivent être synchronisées au préalable. | | `npx gt generate` | Pour créer des modèles de fichiers de traduction à traduire manuellement (aucune clé API nécessaire). | | `npx gt api --spec` | Pour inspecter le contrat OpenAPI fourni avec le CLI installé. | | `npx gt api ` | Pour effectuer une requête API brute authentifiée depuis un script ou un terminal. | | `npx gt project create --org-id --name --default-locale ` | Pour créer un projet avec une clé d'organisation. | | `npx gt project status ` | Pour inspecter un job de traduction ou de génération de contexte de projet. | Ajoutez la traduction au build de production afin que les traductions restent à jour, par exemple : `"build": "npx gt translate && next build"`. ## Règles — à faire et à éviter À faire : - Encapsulez chaque nouveau texte destiné aux utilisateurs dans `` (ou `useGT()`/`getGT()` pour les chaînes autonomes) au moment de l'écrire. - Exécutez `npx gt translate` avant de committer ou de compiler pour la production afin que les nouveaux textes soient traduits. - Conservez la liste des locales uniquement dans `gt.config.json`. - Encapsulez les valeurs dynamiques et privées dans ``, et ajoutez `context` lorsqu'une chaîne est ambiguë. - Après avoir volontairement modifié un fichier de traduction généré, exécutez `npx gt save-local` avant de télécharger à nouveau les traductions, ou passez `--save-local` lors de la prochaine exécution de traduction. À éviter : - Coder en dur des chaînes déjà traduites dans la source, ou ajouter des branches `if`/`switch` par langue — traduisez plutôt le texte source. - Modifier des fichiers de traduction générés sans synchroniser les changements ; un téléchargement ultérieur peut écraser les modifications non enregistrées. - Committer `GT_API_KEY` ou l'exposer au client. - Dupliquer la configuration des locales en dehors de `gt.config.json`. ## Links - [`llms.txt`](/llms.txt) — curated machine-readable docs entry point. - [`llms-index.txt`](/llms-index.txt) — exhaustive index of every docs page. - [`llms-full.txt`](/llms-full.txt) — full docs content for tools that can load a larger context. - [React index](/docs/react/llms.txt), [CLI index](/docs/cli/llms.txt), and [OpenAPI index](/docs/platform/openapi/llms.txt) — focused entry points for common tasks. - [`AGENTS.md`](/AGENTS.md) — this drop-in guide as raw Markdown. - [`openapi.yaml`](/openapi.yaml) — canonical General Translation API specification. - [`sitemap.md`](/sitemap.md) — Markdown index of every docs page and blog post. - [`sitemap.xml`](/sitemap.xml) — standard sitemap for every published page. - Quickstarts: [React](/docs/react/react-quickstart), [Vue](/docs/vue/quickstart), [Node](/docs/node/quickstart), [Core library](/docs/platform/core/quickstart), and the [CLI](/docs/cli/quickstart). - [Key concepts](/docs/overview/key-concepts) — locales, context, and static vs. dynamic content. - Référence du CLI : [`gt api`](/docs/cli/reference/commands/api), [`gt project create`](/docs/cli/reference/commands/project-create) et [`gt project status`](/docs/cli/reference/commands/project-status). ```` ## Orienter 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 point d'entrée organisé, de style [llmstxt.org](https://llmstxt.org/), avec les principaux Quickstarts et des index ciblés. * [`llms-index.txt`](/llms-index.txt) — l'index exhaustif des liens vers chaque page de documentation publiée. * [`llms-full.txt`](/llms-full.txt) — l'intégralité du contenu de la documentation dans un seul fichier, hors référence OpenAPI générée. * [`AGENTS.md`](/AGENTS.md) — le guide prêt à l'emploi ci-dessus en Markdown brut. * [`sitemap.md`](/sitemap.md) — un index Markdown de chaque page de documentation et de chaque article de blog. * [`sitemap.xml`](/sitemap.xml) — le sitemap XML standard de chaque page publiée. Utilisez un index restreint lorsque l'agent sait déjà quelle partie du produit l'intéresse : * [Overview](/docs/overview/llms.txt) * [Platform](/docs/platform/llms.txt), avec des index ciblés pour [Dashboard](/docs/platform/dashboard/llms.txt), [Locadex](/docs/platform/locadex/llms.txt), [Core](/docs/platform/core/llms.txt) et [OpenAPI](/docs/platform/openapi/llms.txt) * [CLI](/docs/cli/llms.txt) * [React](/docs/react/llms.txt) * [Vue](/docs/vue/llms.txt) * [Node.js](/docs/node/llms.txt) * [Python](/docs/python/llms.txt) * [Integrations](/docs/integrations/llms.txt) Pour travailler avec l'API, utilisez le [bundle des opérations OpenAPI](/docs/platform/openapi/llms-full.txt) ou la spécification canonique [`openapi.yaml`](/openapi.yaml) plutôt que d'extraire le contenu des pages interactives des endpoints. L'hôte de la documentation sert également les fichiers racine sous `/docs`, à savoir `/docs/llms.txt`, `/docs/llms-index.txt` et `/docs/llms-full.txt`. Chaque page de documentation est disponible en **Markdown brut** : ajoutez `.md` ou `.mdx` à l'URL d'une page pour récupérer la source propre au lieu d'analyser le HTML affiché. Les index générés et les métadonnées de découverte utilisent `.mdx`, par exemple `/docs/cli/quickstart.mdx`. Pour ajouter la documentation en tant que contexte, collez une URL de 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 documentation. ## Serveur MCP [#mcp] Utilisez le paquet publié [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) lorsque votre agent a besoin d'accéder à la documentation via une connexion [Model Context Protocol](https://modelcontextprotocol.io) (MCP) locale sur l'entrée et la sortie standard : ```json title=".mcp.json" { "mcpServers": { "generaltranslation-docs": { "command": "npx", "args": ["-y", "@generaltranslation/mcp@latest"] } } } ``` Le paquet fournit des outils pour lister et récupérer la documentation. Pour un accès plus simple à la documentation, orientez votre agent directement vers la [documentation lisible par machine](#point-agents). Pour obtenir des informations à jour sur le projet, utilisez le serveur MCP hébergé à l'adresse `https://api.gtx.dev/mcp`. Il utilise le HTTP en streaming. Ajoutez la connexion au fichier de configuration MCP de votre outil (par exemple, `.mcp.json`). Les noms de transport et les champs de configuration peuvent varier d'un client à l'autre : ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### S'authentifier auprès de l'API distante Connectez-vous via le parcours de connexion OAuth de votre client MCP, ou configurez `Authorization: Bearer ` à l'aide de ses paramètres d'en-tête secret. Les connexions par clé d'API acceptent les clés de projet de production (`gtx-api-`) et les Organization keys (`gtx-org-`) ; les development keys ne sont pas acceptées. Le serveur expose les métadonnées de sa ressource protégée et de son serveur d'autorisation. Un client compatible OAuth s'enregistre dynamiquement, utilise le parcours Authorization Code avec Proof Key for Code Exchange (PKCE) et ouvre l'écran de consentement du Dashboard. Demandez `offline_access` lorsque le client a besoin d'un refresh token. Utilisez `list_projects` pour trouver un project ID, puis transmettez-le comme `projectId` aux outils de projet. Une clé de projet de production peut omettre `projectId` pour utiliser son propre projet. Une fois connecté, demandez à votre Agent d'utiliser le serveur MCP `generaltranslation`. Essayez : « Liste mes projets et affiche les paramètres régionaux de l'un d'eux. » ## 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 `CLAUDE.md` à la racine ; copiez donc le [guide d’intégration rapide de l’agent](#agent-guide) dans le `CLAUDE.md` de votre projet. 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 [``](/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 instructions personnalisées) 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 [``](/docs/react/reference/components/var). * **Ne jamais laisser l’agent faire :** modifier les fichiers de traduction générés sans synchroniser les changements, ni coder en dur des chaînes déjà traduites au lieu de traduire le texte source avec la CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.