# General Translation Knowledge Base: Comment internationaliser une application avec Cursor ou Claude Code ? URL: https://generaltranslation.com/fr/kb/ai-agent-i18n-setup.mdx Docs index: https://generaltranslation.com/llms.txt Description: Commencez par le prompt Setup for Agents de General Translation dans Cursor ou Claude Code, choisissez une fonctionnalité et des langues cibles, puis laissez l’agent implémenter et vérifier le résultat. La connexion via le navigateur, la documentation lisible par machine et les outils MCP font le lien entre la configuration initiale, la traduction et la relecture. Utilisez Locadex pour automatiser la localisation continue au moyen de pull requests. Category: Internationalisation Last updated: 2026-10-21 Authors: Kevin Liu, Kevin Wu Published: 2026-10-21 « Traduis mon application en espagnol » : cette consigne laisse plusieurs décisions en suspens. L’agent doit-il conserver une bibliothèque existante ? L’espagnol doit-il disposer de sa propre URL ? Qui traduira les nouveaux textes une fois la session terminée ? Définissez ce cadre avant de lui demander de modifier l’application. General Translation fournit un prompt de configuration initiale, régulièrement mis à jour, qui accompagne un agent de codage dans l’inspection du projet, l’intégration, la traduction et la vérification. Commencez par une seule fonctionnalité opérationnelle, puis étendez l’approche validée à l’ensemble de la base de code. ## Video The video is narrated in English, with English captions. [Can an AI coding agent set up i18n for me?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-ai-agent-i18n-setup.mp4) (46 s) General Translation lets your agent set up i18n with the prompt from Setup for Agents. The prompt has the agent run `gt login`, which you approve in your browser, and run `gt init` with a flag for every question, so the command asks nothing. Then it wraps your page in the `T` component, adds a `LocaleSelector`, runs `gt translate`, builds the app and reports what it actually verified. ## Commencer avec Setup for Agents Utilisez **Setup for Agents** sur generaltranslation.com, ou fournissez à Cursor ou Claude Code le [prompt officiel pour agents](https://generaltranslation.com/agent-prompt.md). Ce prompt demande à l’agent d’examiner votre projet et d’appliquer les instructions à jour propres à votre framework. Pour les projets pris en charge, [`gt init`](/docs/cli/reference/commands/init) propose une configuration initiale expérimentale du framework ; l’agent relit ensuite l’intégration générée, balise le contenu, génère les traductions et vérifie le bon fonctionnement de l’application. Pour accéder au service en local, [`gt login`](/docs/cli/reference/commands/login) vous permet d’approuver la connexion dans le navigateur au lieu de coller une clé API dans le chat. Le projet visé doit toutefois être sélectionné ou configuré dans le CLI. Les options de configuration initiale permettent de répondre aux questions de l’assistant sans terminal interactif, mais la première connexion reste soumise à votre approbation. Pour les compilations non supervisées, utilisez des informations d’authentification à portée limitée, stockées dans le gestionnaire de secrets de votre CI. L’agent peut découvrir la documentation via [`llms.txt`](https://generaltranslation.com/llms.txt), récupérer la source brute en ajoutant `.mdx` à une URL de la documentation et consulter la [spécification OpenAPI](https://generaltranslation.com/openapi.yaml). Le [guide pour les agents de code](/docs/overview/for-coding-agents) fournit des instructions de projet réutilisables. Tenues à jour, ces ressources garantissent que la configuration initiale reste alignée sur les API actuelles du produit. L’[article sur la conception de la documentation](/blog/rewriting-our-docs) explique le fonctionnement de ces interfaces de découverte. ## Confiez à l’agent une tâche bien délimitée Demandez-lui d’examiner le framework, les versions installées, le modèle de rendu, les routes, la configuration i18n existante et les scripts de compilation. Si l’application utilise déjà une bibliothèque d’i18n, conservez-la, sauf si la migration fait partie de la tâche. Le CLI de GT peut [traduire les catalogues existants pris en charge](/docs/cli/guides/generating-translations), notamment ceux de next-intl et de react-i18next. Précisez la langue source, les paramètres régionaux cibles et la fonctionnalité à modifier. Incluez les messages de validation, les espaces réservés, les libellés d’accessibilité et les métadonnées. Choisissez une livraison locale ou via CDN, et désignez la personne chargée de relire le résultat dans l’[Éditeur de Traduction du tableau de bord](/docs/platform/dashboard/guides/reviewing-translations). ## Connecter le serveur MCP de General Translation Le [serveur Model Context Protocol (MCP)](/docs/overview/for-coding-agents#mcp) hébergé par General Translation permet à votre agent de codage d’inspecter en temps réel les paramètres de votre projet et de gérer le contexte de traduction. L’agent peut consulter les paramètres régionaux de votre projet, lire la terminologie partagée et mettre à jour les termes du glossaire ou les instructions personnalisées lorsque la tâche l’exige. Les modifications de code restent ainsi alignées sur les règles de traduction que votre équipe gère dans General Translation. La connexion couvre l’ensemble du workflow de traduction grâce à des outils permettant de : * Traduire du contenu, téléverser des fichiers sources, mettre en file d’attente des tâches de traduction, vérifier leur état et télécharger les résultats. * Publier ou dépublier des traductions sur le CDN. * Découvrir et créer des projets, et créer des clés API de projet à portée limitée lorsque l’autorisation est accordée. * Gérer les groupes de contexte, les termes du glossaire et les instructions personnalisées. Accordez à l’agent les autorisations nécessaires au workflow que vous souhaitez lui confier. Conservez les clés générées dans un gestionnaire de secrets sécurisé, jamais dans le chat ni dans le code côté navigateur. La génération des traductions passe par le service et est facturée à l’usage ; la CLI ci-dessous se charge localement de l’extraction et de la traduction pour l’application. Dans **Cursor**, ajoutez cette entrée de serveur au fichier `.cursor/mcp.json` de votre projet, en conservant les entrées existantes. Consultez la [configuration MCP de Cursor](https://cursor.com/docs/mcp) pour connaître les options de configuration et d’authentification. ```json title=".cursor/mcp.json" { "mcpServers": { "generaltranslation": { "url": "https://api.gtx.dev/mcp" } } } ``` Dans **Claude Code**, enregistrez le même serveur via le [transport HTTP](https://code.claude.com/docs/en/mcp) : ```bash claude mcp add --transport http generaltranslation https://api.gtx.dev/mcp ``` Terminez le flux de connexion OAuth du client, ou configurez une Clé API via ses paramètres d’en-tête secret, comme décrit dans le [guide d’authentification MCP](/docs/overview/for-coding-agents#mcp). La gestion du contexte nécessite un accès au contexte de l’Organisation via OAuth, ou une Clé d’organisation disposant des autorisations de contexte requises ; les clés de projet n’ont pas accès à ces outils. Commencez par une demande concrète : « Utilise le serveur MCP generaltranslation pour lister mes projets et afficher les paramètres régionaux du projet que nous localisons. » Demandez ensuite à l’agent d’examiner les groupes de contexte attribués au projet, qui regroupent les termes de glossaire partagés et les instructions personnalisées. Il peut s’appuyer sur ces termes et instructions pour préparer la fonctionnalité, et les mettre à jour si vous lui avez demandé de modifier la terminologie ou le style. Utilisez la documentation du framework pour intégrer le code, et la CLI pour les étapes d’extraction et de traduction ci-dessous. La connexion MCP donne à l’agent accès au projet en production et à son contexte ; l’application nécessite toujours la configuration initiale de son SDK, le contenu traduit et une vérification. ## Ajouter une description de fonctionnalité avec des critères d'acceptation Ajoutez cette description au prompt officiel de configuration initiale. Remplacez la fonctionnalité et les paramètres régionaux en fonction de vos propres besoins ; l'exemple ci-dessous utilise l'anglais, l'espagnol et le français. ```text Internationalise la fonctionnalité de liste de projets de cette application. Utilise l'anglais comme langue source, et l'espagnol et le français comme langues cibles. Inclus le titre, le nom du propriétaire, le nombre de projets, le champ de recherche, l'étiquette visible, l'espace réservé et le sélecteur de langue. Utilise des traductions incluses localement dans le bundle et conserve les routes et fournisseurs existants. Utilise le serveur MCP GT connecté pour lire les paramètres du projet et la terminologie attribuée lorsque c'est autorisé. Signale tout problème de connexion ou d'autorisation manquante. Ne modifie pas le contexte partagé en dehors de cette tâche. Vérifie les nombres 0, 1 et 2, un nom contenant de la ponctuation, les étiquettes et espaces réservés des champs, le changement de langue, la persistance après rechargement et la compilation de production. Vérifie le contenu server-rendered si cette application utilise le SSR. Indique les commandes réellement exécutées et leurs résultats, l'état de la relecture des traductions et tout ce qui n'a pas été testé. Les modèles source ne sont pas des traductions terminées. Limite les modifications à cette fonctionnalité et à sa configuration initiale. Ne déploie pas et ne fusionne pas. ``` Conservez les règles du projet dans le mécanisme d'instructions lu par votre agent. Cursor documente les [règles de projet et AGENTS.md](https://cursor.com/docs/rules) ; Claude Code documente [CLAUDE.md et les autres instructions de projet](https://code.claude.com/docs/en/memory). Ajoutez à vos instructions existantes la bibliothèque choisie, le paramètre régional source, la commande de traduction et les vérifications obligatoires. Évitez de maintenir plusieurs copies concurrentes, qui risquent de diverger au fil du temps. ## Examiner une implémentation représentative Pour une application React exécutée uniquement dans le navigateur, le [Démarrage rapide pour une SPA React](/docs/react/react-spa-quickstart) configure `gt-react` avant l'affichage. Cet exemple part du principe que cette configuration initiale est terminée et que la sortie locale se trouve dans `src/_gt/[locale].json`. Il utilise `gt-react@11.4.12` et la CLI `gt@2.26.5`. Le composant ci-dessous couvre le texte statique, une valeur dynamique, les formes du pluriel et le texte saisi. Affichez-le en lui transmettant un nombre de projets et un nom de propriétaire issus de votre application. ```tsx title="src/ProjectSummary.tsx" import { Num, Plural, T, Var, useGT } from 'gt-react'; export default function ProjectSummary({ count, ownerName, }: { count: number; ownerName: string; }) { const gt = useGT(); return (

Projects for {ownerName}

You have {count} project.} other={<>You have {count} projects.} />

); } ``` [``](/docs/react/reference/components/var) conserve le nom du propriétaire tandis que le message qui l'entoure est traduit ; sa valeur n'est pas envoyée à l'API de traduction. [``](/docs/react/reference/components/plural) sélectionne une branche selon les règles du paramètre régional, et [``](/docs/react/reference/components/num) met en forme le nombre. [`useGT`](/docs/react/reference/hooks/use-gt) renvoie directement la fonction de traduction. Le libellé visible encapsule le champ de saisie : le contrôle dispose ainsi à la fois d'un libellé et d'un espace réservé traduit. Les branches `one` et `other` décrivent la source en anglais. Les traductions dans les langues cibles doivent représenter leurs propres formes du pluriel ; ne partez pas du principe que tester la paire singulier/pluriel de l'anglais suffit pour toutes les langues. Consultez le [guide de pluralisation React](/kb/how-to-handle-plurals-in-react). Dans une SPA React, la configuration initiale documentée avec [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) charge les traductions avant l'application. Son [`LocaleSelector`](/docs/react/reference/components/locale-selector) enregistre le choix de langue dans un cookie et recharge la page. Les frameworks server-rendered ont des exigences de configuration initiale différentes ; reportez-vous à leur propre guide de démarrage rapide. ## Générer les traductions avant d’évaluer le résultat Pour l’essai en local, exécutez cette commande depuis le répertoire de l’application configuré, après avoir ajouté le composant : ```bash npx gt generate ``` [`gt generate`](/docs/cli/reference/commands/generate) crée des modèles source sans appeler le service de traduction. Renseignez le texte traduit dans les fichiers espagnol et français en conservant les clés générées, les marqueurs de variables et la structure JSX. Le fait que `es.json` existe ne signifie pas qu’il contient de l’espagnol. Pour obtenir des traductions générées par le service, suivez la [procédure d’authentification et de configuration initiale du projet avec la CLI](/docs/cli/quickstart), puis utilisez [`gt translate`](/docs/cli/reference/commands/translate). Authentifiez-vous via une connexion CLI ou une clé API, et configurez l’identifiant de projet séparément : la connexion seule ne sélectionne aucun projet. Pour une CI sans intervention humaine, fournissez `GT_API_KEY` via les paramètres de secrets de votre fournisseur de CI, avec les autorisations requises par le workflow de traduction. Consultez le [guide de configuration des informations d’authentification](/docs/cli/guides/configuring#credentials) et ne placez jamais de clés d’outillage dans le code exécuté côté navigateur. L’utilisation du service est facturée. General Translation traduit le JSX marqué en tenant compte de sa structure et de tout contexte explicite que vous fournissez. Ajoutez la [prop `context`](/docs/react/reference/components/t#context) pour les textes ambigus, et appliquez les [termes du glossaire et les instructions personnalisées](/docs/platform/dashboard/guides/defining-context-for-translations) partagés du projet pour orienter la terminologie et le ton du produit. Ainsi, la production des traductions obéit aux mêmes règles produit que celles que l’agent de codage lit via MCP. Avec des [traductions incluses localement dans le bundle](/docs/react/guides/storing-translations), préparez les fichiers de paramètres régionaux avant la compilation de production. Conservez les fichiers maintenus manuellement dans le contrôle de version ou dans votre pipeline de traduction. N’ignorez pas l’unique copie de traductions modifiées à la main comme s’il s’agissait d’une sortie jetable. ## Vérifier la fonctionnalité, puis étendre Exécutez [`gt validate`](/docs/cli/reference/commands/validate) pour détecter les erreurs de traduction intégrée prises en charge avant toute requête API, puis demandez à l'agent d'indiquer les résultats observés pour chacune des vérifications ci-dessous. | Vérification | Résultat attendu | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Sélectionner l'espagnol, puis le français | Le titre, le message de comptage, le libellé et l'espace réservé s'affichent dans la langue sélectionnée | | Recharger après avoir choisi une langue | La langue sélectionnée est conservée conformément à la politique de l'application | | Essayer les nombres 0, 1 et 2 | Chaque langue applique ses propres règles de pluriel ; le nombre reste correct | | Utiliser un propriétaire tel que O'Connor | Le nom reste intact dans toutes les langues | | Inspecter le nom accessible du champ de saisie | Il correspond au libellé visible traduit | | Exécuter la compilation de production et la prévisualiser | La fonctionnalité se comporte de la même façon avec les fichiers qui seront livrés | Dans cet exemple, [le zéro français et le zéro anglais relèvent de catégories de pluriel différentes](https://cldr.unicode.org/index/cldr-spec/plural-rules). Vérifiez que la phrase affichée utilise la bonne forme et conserve le nombre. Une fois l'approche validée, étendez-la progressivement, une route ou une fonctionnalité à la fois. Les relecteurs peuvent modifier les traductions dans l'[Éditeur de Traduction du tableau de bord](/docs/platform/dashboard/guides/reviewing-translations). Pour inviter des traducteurs, des chefs de projet et des relecteurs locaux, vous devez disposer d'un plan Starter ou Enterprise ; les deux plans incluent un [nombre illimité d'utilisateurs](https://generaltranslation.com/pricing). Le plan Enterprise ajoute l'approbation des traductions. Si votre équipe modifie les fichiers locaux générés, activez [`gt save-local`](/docs/cli/reference/commands/save-local) pour téléverser ces modifications et les réutiliser ultérieurement. Pour le workflow de relecture, consultez [relire les traductions IA](/kb/review-translations). ## Maintenir la localisation après la session de l'agent Placez [`gt translate` avant la compilation de production](/docs/cli/guides/generating-translations) pour mettre à jour les traductions dès que le texte source change. Le workflow incrémental réutilise les traductions existantes au lieu de régénérer tous les messages à chaque exécution. Pour assurer le suivi sans piloter vous-même un assistant de codage, vous pouvez vous appuyer sur l'agent hébergé de General Translation, [Locadex](/docs/platform/locadex/guides/configuring-automations), qui peut internationaliser les nouvelles IU, générer des traductions et synchroniser les paramètres régionaux ajoutés ou supprimés. Configurez des déclencheurs sur pull request, sur push ou manuels ; les modifications sont livrées sous forme de pull requests. L'[auto-merge](/docs/platform/locadex/guides/auto-merging-prs) est facultatif. Un assistant de codage peut mettre en place l'intégration, puis Locadex peut prendre le relais au fil des livraisons suivantes. Locadex nécessite un plan Starter ou Enterprise, et ses exécutions sont facturées à l'[usage](https://generaltranslation.com/pricing/usage). Consultez la [référence des automatisations](/docs/platform/locadex/reference/automations) pour la configuration initiale, ou [exécutez la traduction en CI](/kb/translations-in-ci) avec votre propre pipeline. ## Related questions - [Comment ajouter l’i18n à une application Next.js App Router ?](https://generaltranslation.com/fr/kb/add-i18n-to-nextjs.mdx): Commencez par gt init pour configurer General Translation dans un projet App Router pris en charge, puis balisez le contenu source, générez les traductions et vérifiez le changement de langue. gt-next conserve les textes dans le JSX avec leur contexte de traduction ; la CLI, l’éditeur du tableau de bord et Locadex prennent en charge la génération, la relecture et les mises à jour continues. Ce guide présente également la configuration initiale explicite avec des fichiers locaux. - [Peut-on faire de l’i18n sans fichiers de traduction ?](https://generaltranslation.com/fr/kb/i18n-without-translation-files.mdx): Oui. Les bibliothèques gt-react et gt-next de General Translation permettent d’internationaliser React et Next.js sans clés de traduction ni fichier JSON par langue à maintenir. Le texte reste intégré au JSX, dans le composant ``, et la commande gt translate génère les traductions de chaque langue lors de la compilation, en s’appuyant sur le contexte de votre code. Locadex peut les tenir à jour via des pull requests. - [Comment gérer les formes plurielles dans React ?](https://generaltranslation.com/fr/kb/how-to-handle-plurals-in-react.mdx): Pour gérer les formes plurielles dans React, fournissez à chaque langue une phrase par forme du pluriel et sélectionnez-la selon les règles de pluriel de cette langue, car l’anglais compte 2 formes, le russe 4 et l’arabe 6. Le composant `` de General Translation, disponible dans gt-react et gt-next, prend vos formes source, et General Translation génère les formes requises par chaque langue cible. - [Que fait l’agent Locadex ?](https://generaltranslation.com/fr/kb/what-is-locadex.mdx): Locadex est l’agent IA de General Translation qui internationalise votre code et traduit votre contenu dans votre dépôt GitHub. Ses automatisations s’exécutent à l’ouverture d’une pull request, lors du push d’un commit ou lorsque vous les lancez vous-même, et chaque modification arrive sous forme de pull request. ## Previous and next questions - Previous question: [Comment formater les nombres, les dates et les devises pour chaque paramètre régional ?](https://generaltranslation.com/fr/kb/format-numbers-dates-currencies.mdx) - Next question: [Comment maintenir les traductions à jour à chaque déploiement ?](https://generaltranslation.com/fr/kb/translations-in-ci.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.