# 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 le prompt de démarrage, 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.* ## Prompt de démarrage [#start-prompt] Le prompt ci-dessous lance une session d'agent qui ajoute General Translation à votre projet : l'agent lit le point d'entrée de la documentation, se connecte avec [`gt login`](/docs/cli/reference/commands/login), sélectionne un projet, implémente une première traduction, puis la vérifie. C'est via [`gt login`](/docs/cli/reference/commands/login) qu'un agent interagit avec la plateforme General Translation ; le prompt commence donc par cette commande plutôt que de vous demander une clé API. Le bouton **Setup for Agents** sur [generaltranslation.com](https://generaltranslation.com) copie exactement ce texte, également disponible au format brut à l'adresse [`/agent-prompt.md`](/agent-prompt.md). La commande [`init`](/docs/cli/reference/commands/init) indiquée dans le prompt a été testée avec `gt` 2.24.0 sur un projet `create-next-app` vierge : elle ne pose aucune question, installe `gt-next`, ajoute [`GTProvider`](/docs/react/reference/components/gt-provider) au layout racine et `withGTConfig` à `next.config.ts`, crée `loadTranslations.js` et `gt.config.json`, puis se termine par un événement de succès. ````markdown title="agent-prompt.md" # Get started with General Translation I landed on https://generaltranslation.com and clicked "Setup for Agents". Help me add General Translation to my app, website, or content, and get a real translation working. Inspect the project you have access to, choose the appropriate integration with me, and implement it. Continue through setup, translation, and verification rather than stopping at a plan. ## About General Translation General Translation (GT) combines open-source internationalization libraries, a translation CLI, and a hosted translation platform. Source content stays in your code or content files. The libraries render translations and format locale-sensitive values; the platform generates and manages translations. Locadex is an optional hosted agent that connects to GitHub and maintains localization through pull requests. - Website: https://generaltranslation.com - Dashboard: https://dash.generaltranslation.com - Open-source libraries and CLI: https://github.com/generaltranslation/gt - Documentation entry point: https://generaltranslation.com/llms.txt - Complete documentation index: https://generaltranslation.com/llms-index.txt - API specification: https://generaltranslation.com/openapi.yaml Fetch the documentation entry point first, then the quickstart and references relevant to this project. Documentation pages are available as raw Markdown by appending `.mdx` to the page URL. Use the complete index when you need a page that is not in the curated index. Read current docs and installed command help instead of guessing APIs, flags, or framework setup. `gt auth` is not a command in current releases; use `gt login`. `gt generate` writes source templates without calling the API and is registered when the CLI detects `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, `gt-node`, `gt-vue`, `gt-flask`, or `gt-fastapi`. Use `gt translate` for hosted translation. ## Work with me Read this entire prompt before acting. Respect the repository's instructions, package manager, architecture, design system, and existing changes. First inspect the repository for the framework, router, app directory, existing i18n library, GT configuration, source language, and build scripts. In a monorepo, identify the specific app or content directory; do not run setup at the workspace root. Do not ask me things you can determine from the code. If the intended project is unclear, ask one question: "What would you like to translate?" Offer concrete choices: this app or website, documentation or content files, a backend service, a connected content platform, or a small new demo. Include "Not sure, help me decide." Prefer your interactive question tool when available. If no repository is open, help me open one or choose a small demo before scaffolding anything. Ask for missing decisions one at a time: source language, target languages, and the first page or workflow to translate. Preserve existing locale choices; do not assume the source language is English or invent target markets. If I want help choosing, propose one target language for the first working example. Reuse an existing i18n setup where appropriate instead of automatically migrating the entire application. Explain the next meaningful step briefly, then do the work. Ask when a choice affects which organization/project you use, creates an unwanted duplicate, or changes the agreed scope. Once I have chosen the project, languages, and scope, proceed with the setup and translation needed for that outcome. ## Choose the right integration Read the matching quickstart before making framework changes: | Project | Integration | Quickstart | | --- | --- | --- | | Next.js App Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-quickstart.mdx | | Next.js Pages Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-pages-router-quickstart.mdx | | React SPA, including Vite | `gt-react` | https://generaltranslation.com/docs/react/react-spa-quickstart.mdx | | Server-rendered React | `gt-react` | https://generaltranslation.com/docs/react/react-quickstart.mdx | | TanStack Start | `gt-tanstack-start` | https://generaltranslation.com/docs/react/tanstack-start-quickstart.mdx | | React Native or Expo | `gt-react-native` | https://generaltranslation.com/docs/react/react-native-quickstart.mdx | | Vue | `gt-vue` | https://generaltranslation.com/docs/vue/quickstart.mdx | | Node.js backend | `gt-node` | https://generaltranslation.com/docs/node/quickstart.mdx | | Python backend | Follow the Python SDK guide | https://generaltranslation.com/docs/python/quickstart.mdx | | JSON, MDX, Markdown, YAML, or existing translation files | `gt` CLI | https://generaltranslation.com/docs/cli/quickstart.mdx | | Lower-level JavaScript translation | `generaltranslation` | https://generaltranslation.com/docs/platform/core/quickstart.mdx | For Mintlify, Sanity, Storyblok, or Google Drive, fetch https://generaltranslation.com/docs/integrations/llms.txt and follow that integration's quickstart. Do not apply a React setup wizard to a content integration. If I want GT to continuously maintain localization through GitHub, read https://generaltranslation.com/docs/platform/locadex/quickstart.mdx and walk me through connecting the repository and creating the appropriate automation. Do not enable auto-merge or change paid plans without my direction. ## Run the CLI without questions The CLI is interactive. When `init` or `configure` is missing an answer, it does not fail: it asks the question in the terminal and waits, with no timeout. In an agent session that wait never ends. So in this session: - Always pass `--no-interactive`. With it, a missing answer is a hard error that lists the flags still needed and changes no file. - Pass a flag for every question before you run the command. `--defaults` accepts the recommended local choices in one flag; you still need `--locales` and, outside local Vite and TanStack Start setups, `--dev-credentials` or `--no-dev-credentials`. Pass explicit `--default-locale`, `--locadex` or `--no-locadex`, `--react-setup` or `--no-react-setup`, and `--file-formats` values only when you want to override the defaults. Local Vite and TanStack Start setups default to `--no-live-translations`; pass `--live-translations` to opt in. Never combine the `--[no-]live-translations` and `--[no-]dev-credentials` flag families. - Pass `--json` to `init` and `configure`. It implies `--no-interactive`, writes one result event to stdout and the rendered screen to stderr. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` have no `--json` flag; `translate` prints a progress screen with terminal control sequences, so judge it by its exit code and by the files it writes: `public/_gt/.json`, `gt-lock.json` and `gt.config.json`. - If a command prints a question and stops, you are inside an interactive prompt. End the process and rerun it with `--no-interactive` and the missing flag. Never type an answer into it, and never run a command whose questions you have not answered with flags. - `gt login` is the one step that needs a person: it opens a browser and waits for the sign-in to finish. If no browser can open from this session, run it with `--no-browser`, give me the URL it prints, and wait for me to confirm. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` ask nothing when their flags are complete; a missing required flag is an error. ## Sign in with `gt login` Use account login for local CLI authentication. Do not begin by asking me to find and paste an API key. The examples below use `npx gt@latest` to avoid an old local CLI. Use the project's package manager or a current installed `gt` binary when appropriate. Inspect the version and available commands first: ```bash npm view gt version npx gt@latest --help npx gt@latest login --help ``` The CLI has no `--version` flag. `translate` prints "CLI Version: x.y.z" in its banner; `init --json` prints no banner. Read the published version with `npm view gt version` and the installed one from `node_modules/gt/package.json`. This workflow requires a CLI release with `login`, `whoami`, and `api-key create`. If the installed CLI lacks them, check the latest published release. If they are still unavailable, explain the release blocker and continue with local integration work that does not require credentials. Do not silently substitute the older `gt auth` flow, invent flags, or install an unpublished branch into my project. Check for an existing session with `npx gt@latest whoami`. If sign-in is needed, run: ```bash npx gt@latest login ``` Let me complete signup/sign-in and authorization in the browser. Keep the command running while approval is pending. In a remote or headless terminal, use: ```bash npx gt@latest login --no-browser ``` Show me the verification URL and code returned by that command; wait for successful authorization, then verify with `npx gt@latest whoami`. Do not ask for my password or extract OAuth tokens. Login authenticates the CLI; it does not by itself configure the app's project or create its runtime credentials. ## Select a project and create the credentials we need Reuse an existing configured project if it is the intended one. Check for conflicting project IDs in configuration and environment variables without printing secret values. Do not overwrite existing credentials or create another key unnecessarily. For a supported fresh app, run the setup wizard from the app directory after login, with every question answered by a flag. For a Next.js App Router app set up locally, with translations stored in the repository and an existing project reused: ```bash npx gt@latest init --no-interactive --json --defaults \ --default-locale --locales \ --no-locadex --react-setup --file-formats none \ --no-dev-credentials --project-id ``` This run asks nothing, installs gt-next, adds GTProvider to the root layout, adds withGTConfig to next.config.ts, creates loadTranslations.js and gt.config.json, and ends with `{"type":"result","command":"init","outcome":"success"}`. The wizard does not wrap any page text in ``, even though its completedSteps list says "wrapped JSX content". Internationalize every page yourself in step 4 of the implementation section. The wizard runs biome on the files it changes and may replace the project's indentation with tabs; restore the project's formatting. Ignore the warning "Unexpected export type in ./next.config.ts" when withGTConfig() was added correctly. Review the wizard's changes against the framework quickstart: automatic framework setup is experimental. `--defaults` covers local storage and the translations directory; pass `--storage` and `--translations-dir` only for other values. `--no-dev-credentials --project-id ` writes projectId to gt.config.json and creates no env file. Use it when no development key is wanted. If you already have a development key, add `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY` to `.env.development.local` yourself. `--dev-credentials --project-id ` saves a new development key and the project ID to `.env.local` instead; `--create-project --org-id --project-name ` creates the project first. `--no-react-setup` is for an app that already has the GT library; on an app without one it fails with "No GT runtime is installed, so select at least one file format to translate", which is right, since there would be nothing to translate. Pass `--locadex` only if we agreed to use hosted automation. Before a production build, move the development key (`NEXT_PUBLIC_GT_DEV_API_KEY` or `GT_DEV_API_KEY`) from `.env.local` to `.env.development.local`: `next dev` loads that file and `next build` does not, and a production build refuses to run with a development key present. A production build that ships local translation files needs no key. If the app already has framework setup, configure it directly from the docs. Use the authenticated CLI to discover resources: ```bash npx gt@latest api /v2/projects npx gt@latest api /v2/orgs ``` Follow pagination when present by passing `nextCursor` as `?cursor=`. `/v2/orgs` lists the organizations the signed-in user belongs to (an API key sees only its own). Creating a project also needs the `org:projects:create` permission in that organization; when `project create` is refused, ask me which organization to use or create the project in the Dashboard at https://dash.generaltranslation.com. Use actual returned IDs. Ask me to select when the destination is ambiguous. If my new account has no suitable organization, guide me through creating one at https://dash.generaltranslation.com, then retry discovery. When a new project is needed in the chosen organization: ```bash npx gt@latest project create \ --org-id \ --name \ --default-locale ``` Use the returned project ID. `project create` may require an organization key; read `npx gt@latest project create --help` first and fall back to creating the project in the Dashboard. For endpoint details or a missing higher-level command, inspect `npx gt@latest api --spec` and the current API docs before making a request. Local CLI operations can use the login session. Create separate project keys only where a runtime or unattended CI workflow needs one. Inspect `npx gt@latest api-key create --help` first. The command requires a key name and explicit permissions. A development runtime key needs `project:translations:generate`; a standard file translation workflow needs `project:files:read`, `project:files:write`, and `project:translations:enqueue`. Verify any additional operations against the API specification; do not grant every permission by default. `gt api-key create` prints the secret once to stdout. Capture that output directly into protected, ignored local configuration or the intended secret store without displaying it in tool output, chat, or logs. Use `--project-id` for the selected project, `--name` for its purpose, and `--permission` for the required permissions. Confirm success and the variable names without showing the key. Keep these credential roles distinct: - CLI/CI and server credentials use `GT_API_KEY` and `GT_PROJECT_ID`. Never put `GT_API_KEY` in browser code or a public-prefixed variable. - Development runtime translation uses `GT_DEV_API_KEY` and a project ID. Browser frameworks may need their documented public prefix, such as `VITE_GT_DEV_API_KEY`; for Next.js the wizard writes `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY`, and the CLI reads that project ID too, so `GT_PROJECT_ID` is only needed in CI. Only expose the narrowly scoped development key where the framework guide requires it; do not ship development credentials in production browser bundles. - OAuth credentials belong in the CLI's credential store. Do not copy them into the app or CI. Ensure local environment files are ignored by Git. Use placeholders in committed examples. Preserve unrelated environment settings. Logging in locally does not authenticate CI or a deployed server. ## Implement a complete first translation 1. Install the integration that matches the detected stack. For an existing project, make targeted changes and preserve its current behavior. 2. Create or update `gt.config.json` with the agreed source and target locales, source paths, and file mappings. Use the current configuration reference: https://generaltranslation.com/docs/cli/reference/config.mdx. Preserve existing settings. Configure translation output and loading together; for example, a Vite SPA's imported translation files must live within its source tree. Do not copy one framework's output path or provider setup into another framework. Add the translation output directory (for example `public/_gt/`) to `.gitignore` when translations are not committed. 3. Follow the framework's initialization and routing guide. Next.js App Router and Pages Router differ; React SPAs use `initializeGTSPA` before rendering; server runtimes need request-aware locale handling. Read the installed version's APIs before implementing them. 4. Internationalize the agreed page or workflow, including visible text, validation, placeholders, accessible labels, and metadata where relevant. In React, use `` for coherent static JSX. For standalone strings in gt-next, use `useGT()` in client components and in synchronous server components, and `getGT()` from `gt-next/server` in async server components and in `generateMetadata`. `useGT()` returns the function directly. For Next.js metadata, replace the static `metadata` export with `export async function generateMetadata()` that calls `getGT()` from `gt-next/server` and returns the translated title and description. Use `` or the framework's interpolation API for dynamic values; keep private values out of translation source. Use locale-aware number, date, currency, and plural handling. Follow the matching Vue, Node, or Python APIs for those stacks. 5. Add a language switcher to a suitable place in an app's existing UI. In gt-next, `` from `gt-next` renders directly inside a server component page; it carries its own client boundary. Give it an `aria-label` through `useGT()`. Preserve navigation and verify the selected locale survives navigation or reload as documented. For a backend or content-only project, verify locale selection and translated output through its actual API or content workflow instead. 6. Add useful context for ambiguous copy. Use the `context` prop on `` and the `$context` option in `gt()` and `getGT()` calls. `$context` on `` is a deprecated alias that the CLI flags when it scans the source. Preserve product names and terminology. Do not send secrets or runtime user data as translation source. For content files, preserve frontmatter, links, variables, and formatting according to the format guide. 7. Inspect the translation scope with `npx gt@latest translate --dry-run`, then run `npx gt@latest translate` for the agreed languages and scope. If this would unexpectedly translate a large corpus or exceed the agreed scope, clarify that before submitting it. `gt translate` also writes `gt-lock.json` and a `_versionId` into `gt.config.json`; commit both. Use the connected-platform workflow instead when the integration requires one. ## Verify and finish Exécute la vérification des types (`npx tsc --noEmit`) et le build de production (`next build`). N'exécute le lint et les tests que si le projet les définit déjà. Lorsque des outils de navigateur sont disponibles, démarre l'application et vérifie le rendu traduit en conditions réelles : bascule entre les paramètres régionaux source et cibles, navigue, recharge la page, puis contrôle l'interpolation et la mise en page. Une requête sans en-tête `Accept-Language` ni cookie affiche le paramètre régional par défaut et journalise un avertissement « gt-next: No locale could be determined » à chaque recherche de traduction ; c'est le comportement attendu avec curl sans en-tête. Envoie `Accept-Language: ` ou `Cookie: generaltranslation.locale=` pour vérifier un paramètre régional cible. Vérifie les textes longs et la mise en page de droite à gauche si la langue choisie l'exige. Pour les projets backend et de contenu, examine des réponses ou des fichiers réellement traduits. N'affirme pas avoir vérifié dans le navigateur si tu n'as pas pu le faire. Corrige les échecs de setup ou d'exécution avant de considérer l'intégration comme terminée. En cas de blocage, consulte la référence pertinente et analyse les erreurs des commandes plutôt que de recréer sans cesse des projets ou des clés. Pour les applications qui utilisent des traductions prégénérées, prépare le workflow de production de sorte que la traduction s'exécute avant le build existant et que les fichiers générés soient accessibles au runtime. Préserve les étapes de build existantes, documente les noms des secrets CI et vérifie les exigences de l'intégration choisie en matière de fichiers locaux ou de CDN. Si les traductions sont commitées et qu'aucune clé CI n'existe, ne modifie pas le script de build. À chaque modification du texte source, exécute `npx gt@latest translate` en local avec la session de connexion, puis committe `public/_gt/.json`, `gt-lock.json` et `gt.config.json`. N'ajoute `npx gt translate` au script de build que si une `GT_API_KEY` disposant des permissions d'écriture de fichiers et de file d'attente de traduction est définie dans la CI. N'utilise `--publish` que si le workflow CDN choisi l'exige. N'effectue aucun déploiement en production et ne fusionne aucune pull request sans que je te l'aie demandé. Termine par un compte rendu concis : ce qui a changé, quel projet et quels paramètres régionaux sont configurés, comment le lancer, ce que tu as réellement vérifié et les éventuelles actions qu'il me reste à effectuer. Inclus les liens vers la documentation pertinente et le Dashboard, mais aucun identifiant. L'objectif est d'obtenir une traduction fonctionnelle dans mon projet, avec une marche à suivre claire pour la maintenir à jour. ```` ## 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` - **TanStack Start** → `gt-tanstack-start` - **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 For a new setup, run from the app directory with `--no-interactive` and a flag for every question. Without `--no-interactive`, a missing answer opens a question in the terminal and the command waits for it; with it, a missing answer is an error that lists the flags still needed and changes no file: ```bash npx gt init --no-interactive --json --defaults --default-locale en --locales fr es --no-locadex --react-setup --file-formats none --no-dev-credentials ``` For a local Vite or TanStack Start setup, replace `--no-dev-credentials` with `--no-live-translations`. Do not pass both credential flag families. The wizard detects the framework, creates or updates `gt.config.json`, and can select/create a project and provision a development runtime key. Creating a project or key without a tooling key or saved login signs in first, which a person must approve. Framework rewrites are experimental and need review. Review [init flags and side effects](/docs/cli/reference/commands/init) before running it. 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. For a manually configured app, have the developer run `npx gt login`, then bind an existing project with `projectId` in the config or `GT_PROJECT_ID` in the environment. Login does not select a project or write env files; do not rerun init just to authenticate. For CI, commit the config and inject a separately scoped tooling key through the CI secret store: ```bash GT_API_KEY="your-api-key" # Grants for the entire CLI workflow, not just generation GT_PROJECT_ID="your-project-id" ``` CLI login, runtime development keys, and CI tooling keys are separate. SDKs do not read CLI sessions; init's development runtime key does not replace `GT_API_KEY`. Never commit keys or include them in deployed browser/mobile bundles. Read [CLI credentials](/docs/cli/guides/configuring#credentials) before configuring authentication. Require human approval for login and key creation; `--no-browser` and quiet mode do not make login unattended. ## 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` | Configuration guidée ; s'exécute sans interface avec `--no-interactive` et des options. Peut modifier les fichiers du framework, les dépendances, la configuration et les identifiants d'exécution. | | `npx gt configure` | Configuration sans la réécriture React ; accepte les mêmes options, à l'exception de la configuration du framework. Peut installer des dépendances et provisionner des identifiants d'exécution. Pour ne modifier que la configuration, écrivez-la manuellement. | | `npx gt login` | Demandez au développeur d'approuver l'accès au compte pour les opérations du CLI. | | `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 générer des modèles source destinés à la traduction manuelle, sans appeler l'API. Disponible pour les paquets pris en charge répertoriés dans la référence [`gt generate`](/docs/cli/reference/commands/generate). | | `npx gt translate --dry-run` | Pour examiner le périmètre de traduction sans appeler l'API ni écrire de fichiers de traduction. | | `npx gt api --list` | Pour lister les opérations d'API fournies avec le CLI installé. | | `npx gt api --spec ` | Pour inspecter une opération d'API fournie par ID d'opération, chemin de spécification ou chemin de requête concret. Omettez l'endpoint pour obtenir la spécification complète. | | `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 ` | Après approbation, pour créer un projet à l'aide d'un utilisateur connecté ou d'une clé d'organisation disposant de l'autorisation org:projects:create. | | `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. - Si vous êtes autorisé à envoyer du contenu vers la traduction hébergée, 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 ou exposer des clés API, consigner la sortie standard de création de clés dans des journaux partagés, ou générer des identifiants sans approbation explicite. - 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. - Commandes de compte : [`gt login`](/docs/cli/reference/commands/login) et [`gt api-key create`](/docs/cli/reference/commands/api-key-create). - 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. * [`agent-prompt.md`](/agent-prompt.md) : le prompt de démarrage 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 serveur [Model Context Protocol](https://modelcontextprotocol.io) (MCP) hébergé à l'adresse `https://api.gtx.dev/mcp` pour obtenir des informations à jour sur le projet et gérer le contexte. Il utilise le HTTP en streaming. Les outils de gestion du contexte du serveur permettent de lister, créer et mettre à jour les groupes de contexte, leurs termes de glossaire et instructions personnalisées, leurs imports et exports, ainsi que leurs affectations aux projets. Ils reprennent les fonctionnalités de l'[API de gestion du contexte](/docs/platform/openapi/reference/context-management/list-groups). Le serveur hébergé fournit également des [outils MCP Google Drive](/docs/integrations/google-drive/reference/mcp-tools) pour trouver les projets connectés, traduire des Google Docs et des Google Slides, et suivre la progression des copies traduites. 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é API acceptent les clés de projet (`gtx-api-`) et les clés d'organisation (`gtx-org-`). Les clés `gtx-dev-` existantes restent authentifiées en tant que clés de projet. Chaque outil vérifie les permissions de la clé pour l'action demandée. Configurez des [permissions de clé personnalisées](/docs/platform/dashboard/reference/api-keys) pour les outils dont votre Agent a besoin. Utilisez `list_orgs` pour trouver un identifiant d'organisation et `list_projects` pour trouver un project ID. Aucun de ces outils de découverte ne nécessite de permission sur une ressource. Transmettez les identifiants renvoyés comme `orgId` et `projectId` aux autres outils. Les clés de projet et les clés d'organisation ne découvrent que les ressources auxquelles elles sont liées, et une clé de projet peut omettre `projectId` pour utiliser son propre projet. Les outils de gestion du contexte nécessitent `org:context:read` ou `org:context:write`. Accordez à une clé d'organisation la permission **Context** correspondante, ou autorisez ce même accès au contexte de l'organisation lors de la connexion OAuth MCP. Les clés de projet ne peuvent pas utiliser ces outils. Transmettez un `orgId` à `list_context_groups` et `create_context_group`, et un `groupId` aux outils qui agissent sur un groupe existant. Le corps des requêtes MCP est limité à 100 Mio. Certains outils peuvent imposer des limites plus basses pour leurs entrées. 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 et générer le squelette de `gt.config.json`. Obtenez une approbation avant d’exécuter [`npx gt init`](/docs/cli/reference/commands/init) avec `--dev-credentials` ou `--create-project`, qui créent des clés ou des projets. * **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 :** créer ou exposer des identifiants sans approbation, 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.