# General Translation Overview: Using coding agents
URL: https://generaltranslation.com/en-GB/docs/overview/for-coding-agents.mdx
---

title: Using coding agents
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.

````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`
- **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 `<T>`. Write source copy directly — no translation keys needed:

```tsx
import { T } from 'gt-next'; // or 'gt-react'

/* Everything inside <T> is translated as a unit */
<T>
  <h1>Welcome to my app</h1>
</T>;
```

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

<input placeholder={gt('Search products')} />;
```

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 `<Var>` so they are not translated and never sent to the API. Use `<Currency>`, `<DateTime>`, and `<Num>` for values that should be reformatted but not translated:

```tsx
import { T, Var } from 'gt-next';

// Generates one translation, keeps the name unchanged
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

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. |
| `npx gt generate` | To create translation file templates to translate manually (no API key needed). |

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 `<T>` (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 `<Var>`, and add `context` when a string is ambiguous.

Don't:

- Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead.
- Hand-edit generated translation files (the CLI overwrites them).
- Commit `GT_API_KEY` or expose it to the client.
- Duplicate the locale configuration outside `gt.config.json`.

## Links

- [`llms.txt`](/llms.txt) — short, machine-readable docs index.
- [`sitemap.md`](/sitemap.md) — map of every docs page.
- Quickstarts: [React](/docs/react/react-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.
````

## 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:

* [`llms.txt`](/llms.txt) — a short, [llmstxt.org](https://llmstxt.org/)-style index of the docs.
* [`sitemap.md`](/sitemap.md) — a linked map of every page in navigation order.

Every docs page is also available as **raw Markdown**: append `.md` to any page URL (for example, `/docs/cli/quickstart.md`) to fetch the clean source instead of parsing rendered HTML.

To add the docs as context, paste a docs URL or the `llms.txt` link into your agent&#39;s context, or add the docs as a source in tools that support documentation indexing.

## MCP server [#mcp]

General Translation offers a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets agents query the docs directly. It comes in two forms:

* **Local (stdio)** — the published [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) npm package, run on your machine with `npx`. Best for tools that maintain a persistent connection, such as Cursor and Claude Code.
* **Remote (HTTP/SSE)** — a hosted endpoint at `https://mcp.gtx.dev`. Use the SSE endpoint only if your tool does not support streamable HTTP.

Configure the connection using whichever transport your tool supports. The config shape is identical across tools — add it to your tool&#39;s MCP config file (for example, `.mcp.json`):

<Tabs items={['Local', 'Streamable HTTP', 'SSE']}>
  <Tab value="Local">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Streamable HTTP">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Once connected, ask your agent to use the `generaltranslation` MCP server. *Example: &quot;Use the generaltranslation MCP server to explain how to use a [`<T>`](/docs/react/reference/components/t) component.&quot;*

## 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 &quot;use the `generaltranslation` tool&quot;. Add the docs as a source, or reference `/llms.txt` in your prompt.
* **Claude Code** — reads a root `AGENTS.md` automatically, so dropping the [agent guide](#agent-guide) into your project&#39;s `AGENTS.md` is enough to prime it. Register the MCP server and ask it to &quot;use the `generaltranslation` MCP server&quot;.
* **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 `<T>`, adding [`useGT()`](/docs/react/reference/hooks/use-gt) for standalone strings, scaffolding `gt.config.json`, and running `npx gt init`.
* **Verify by hand:** the [translation context](/docs/overview/key-concepts#context) (Glossary and Directives) the agent writes, the locale configuration (`defaultLocale` and `locales`), and that dynamic or private values are wrapped in [`<Var>`](/docs/react/reference/components/var).
* **Never let the agent do:** manually editing generated translation files, or hard-coding already translated strings instead of translating source copy with the CLI.