# General Translation Overview: Using coding agents URL: https://generaltranslation.com/en-GB/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt Description: How to use AI coding agents and LLMs with General Translation by pointing them at the machine-readable docs, the MCP server, and our drop-in agent guide. General Translation is built to work with AI coding agents and LLMs. The libraries are open-source, configuration is predictable, and the docs are published in machine-readable formats. An agent such as Cursor, Claude Code, or Copilot can add and run General Translation for you with accurate, current context. *For fully automated localisation that opens pull requests on its own, use our dedicated agent [Locadex](/docs/platform/locadex/quickstart) instead of driving your own agent.* ## Drop-in agent guide [#agent-guide] Give your agent everything it needs in a single paste. Copy the guide below into an `AGENTS.md` (or `CLAUDE.md`, a Cursor rule, or your tool's instructions file) at your project root, and your agent will add and run General Translation correctly. Use the copy button in the top right of the block, or fetch the same guide directly from [`/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, initialise 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; add `--save-local` only when local edits should sync first. | | `npx gt generate` | To create translation file templates to translate manually (no API key needed). | | `npx gt api --spec` | To inspect the OpenAPI contract bundled with the installed CLI. | | `npx gt api ` | To make an authenticated raw API request from a script or terminal. | | `npx gt project create --org-id --name --default-locale ` | To create a project with an Organization key. | | `npx gt project status ` | To inspect a translation or project context-generation job. | 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 `` (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 ``, and add `context` when a string is ambiguous. - After deliberately editing a generated translation file, run `npx gt save-local` before downloading translations again, or pass `--save-local` to the next translation run. Don't: - Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead. - Edit generated translation files without syncing the changes; a later download can overwrite unsaved edits. - Commit `GT_API_KEY` or expose it to the client. - Duplicate the locale configuration outside `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. - CLI reference: [`gt api`](/docs/cli/reference/commands/api), [`gt project create`](/docs/cli/reference/commands/project-create), and [`gt project status`](/docs/cli/reference/commands/project-status). ```` ## Point agents at the docs [#point-agents] Give your agent direct access to the docs so its answers stay accurate. General Translation publishes several machine-readable entry points at the site root and under `/docs` on the docs host: * [`llms.txt`](/llms.txt) — a curated [llmstxt.org](https://llmstxt.org/)-style entry point with primary Quickstarts and focused indexes. * [`llms-index.txt`](/llms-index.txt) — the exhaustive link index for every published docs page. * [`llms-full.txt`](/llms-full.txt) — full docs content in one file, excluding the generated OpenAPI reference. * [`AGENTS.md`](/AGENTS.md) — the drop-in guide above as raw Markdown. * [`sitemap.md`](/sitemap.md) — a Markdown index of every docs page and blog post. * [`sitemap.xml`](/sitemap.xml) — the standard XML sitemap for every published page. Use a scoped index when the agent already knows which part of the product it needs: * [Overview](/docs/overview/llms.txt) * [Platform](/docs/platform/llms.txt), with focused indexes for [Dashboard](/docs/platform/dashboard/llms.txt), [Locadex](/docs/platform/locadex/llms.txt), [Core](/docs/platform/core/llms.txt), and [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) For API work, use the [OpenAPI operation bundle](/docs/platform/openapi/llms-full.txt) or the canonical [`openapi.yaml`](/openapi.yaml) specification instead of scraping interactive endpoint pages. The docs host also serves the root files under `/docs`, including `/docs/llms.txt`, `/docs/llms-index.txt`, and `/docs/llms-full.txt`. Every docs page is available as **raw Markdown**: append `.md` or `.mdx` to any page URL to fetch the clean source instead of parsing rendered HTML. Generated indexes and discovery metadata use `.mdx`, for example `/docs/cli/quickstart.mdx`. To add the docs as context, paste a docs URL or the `llms.txt` link into your agent's context, or add the docs as a source in tools that support documentation indexing. ## MCP server [#mcp] Use the published [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) package when your agent needs documentation through a local [Model Context Protocol](https://modelcontextprotocol.io) (MCP) connection over standard input and output: ```json title=".mcp.json" { "mcpServers": { "generaltranslation-docs": { "command": "npx", "args": ["-y", "@generaltranslation/mcp@latest"] } } } ``` The package provides tools to list and fetch documentation. For simpler documentation access, point your agent at the [machine-readable docs](#point-agents) directly. For live project information, use the hosted MCP server at `https://api.gtx.dev/mcp`. It uses streamable HTTP. The hosted server also provides [Google Drive MCP tools](/docs/integrations/google-drive/reference/mcp-tools) for finding connected projects, translating Google Docs and Google Slides, and polling translated-copy progress. Add the connection to your tool's MCP config file (for example, `.mcp.json`). Transport names and configuration fields can vary by client: ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### Authenticate with the remote API Connect through your MCP client's OAuth sign-in flow, or configure `Authorization: Bearer ` using its secret-header settings. API-key connections accept production project keys (`gtx-api-`), development project keys (`gtx-dev-`), and Organization keys (`gtx-org-`). Each tool decides whether development keys are allowed; runtime translation and the [Google Drive MCP tools](/docs/integrations/google-drive/reference/mcp-tools) accept them, while other tools can reject them. The server advertises its protected-resource and authorisation-server metadata. An OAuth-capable client registers dynamically, uses the Authorization Code flow with Proof Key for Code Exchange (PKCE), and opens the Dashboard consent screen. Request `openid` and `profile` for identity claims, and request `offline_access` when the client needs a refresh token. Use `list_projects` to find a project ID, then pass it as `projectId` to the project tools. A production project key can omit `projectId` to use its own project. Once connected, ask your agent to use the `generaltranslation` MCP server. Try: "List my projects and show the locale settings for one of them." ## Editor-specific tips [#editor-tips] Most setup is the same across agents; these are the few places the guidance differs. * **Cursor** — register the MCP server, then ask it to "use the `generaltranslation` tool". Add the docs as a source, or reference `/llms.txt` in your prompt. * **Claude Code** — reads a root `CLAUDE.md` automatically, so copy the [agent guide](#agent-guide) into your project's `CLAUDE.md`. Register the MCP server and ask it to "use the `generaltranslation` MCP server". * **Copilot** — put repo-wide guidance in your instructions file (for example, `.github/copilot-instructions.md`) and reference the docs `/llms.txt` there. ## Best practices [#best-practices] Agents are reliable for mechanical i18n work, but translation quality and configuration still require a human. Use this split: * **Hand to the agent:** wrapping user-facing copy in [``](/docs/react/reference/components/t), adding [`useGT()`](/docs/react/reference/hooks/use-gt) for standalone strings, scaffolding `gt.config.json`, and running [`npx gt init`](/docs/cli/reference/commands/init). * **Verify by hand:** the [translation context](/docs/overview/key-concepts#context) (Glossary and Custom Prompts) the agent writes, the locale configuration (`defaultLocale` and `locales`), and that dynamic or private values are wrapped in [``](/docs/react/reference/components/var). * **Never let the agent do:** editing generated translation files without syncing the changes, or hard-coding already translated strings instead of translating source copy with the CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.