# General Translation Overview: Using coding agents URL: https://generaltranslation.com/en-US/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 localization 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 one 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, initialize once and resolve translations per request: ```js import { initializeGT, withGT, getGT } from 'gt-node'; initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] }); // wrap handlers in withGT(locale, ...); then `const gt = await getGT()` inside them ``` Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase. ## Commands | Command | When to run | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx gt init` | Once, to set up a project (installs deps, configures the framework, creates `gt.config.json`, generates credentials). | | `npx gt configure` | To create or update `gt.config.json` (locales and files) without the full wizard. | | `npx gt auth` | To generate or refresh API credentials. | | `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production; 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. 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-`) and Organization keys (`gtx-org-`); development keys are not accepted. The server advertises its protected-resource and authorization-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 `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 need 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 hardcoding already-translated strings instead of translating source copy with the CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.