# General Translation Knowledge Base: How do I internationalise an app with Cursor or Claude Code?
URL: https://generaltranslation.com/en-GB/kb/ai-agent-i18n-setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Start with General Translation's Setup for Agents prompt in Cursor or Claude Code, choose a feature and target languages, and have the agent implement and verify the result. Browser sign-in, machine-readable docs and MCP tools connect set-up to translation and review. Use Locadex to automate ongoing localisation through pull requests.
Category: Internationalisation
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

‘Translate my app into Spanish’ leaves several decisions unanswered. Should the agent keep an existing library? Does Spanish need its own URL? Who translates new copy once this session ends? Set those boundaries before asking it to edit the application.

General Translation provides a maintained set-up prompt that takes a coding agent through project inspection, integration, translation and verification. Start with one working feature, then apply the verified pattern across the codebase.

## 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 secs)

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.

## Start with Setup for Agents

Use **Setup for Agents** on generaltranslation.com, or give Cursor or Claude Code the [official agent prompt](https://generaltranslation.com/agent-prompt.md). It directs the agent to inspect your project and follow the current framework instructions. For supported projects, [`gt init`](/docs/cli/reference/commands/init) offers experimental framework set-up; the agent then reviews the generated integration, marks content, generates translations and verifies the app.

For local service access, [`gt login`](/docs/cli/reference/commands/login) lets you approve sign-in in the browser rather than pasting an API Key into chat. The CLI still needs the intended project to be selected or configured. Set-up flags can answer wizard questions without an interactive terminal, but initial sign-in still requires your approval. For unattended builds, use scoped credentials from your CI secret store.

The agent can discover documentation through [`llms.txt`](https://generaltranslation.com/llms.txt), fetch clean source by appending `.mdx` to a docs URL, and consult the [OpenAPI specification](https://generaltranslation.com/openapi.yaml). The [coding-agent guide](/docs/overview/for-coding-agents) includes reusable project instructions. Because these resources are actively maintained, set-up stays aligned with the current product APIs. The [documentation design article](/blog/rewriting-our-docs) explains how these discovery surfaces work.

## Give the agent a bounded task

Ask it to inspect the framework, installed versions, rendering model, routes, existing i18n configuration and build scripts. If the app already uses an i18n library, keep it unless migration is part of the task. GT's CLI can [translate supported existing catalogues](/docs/cli/guides/generating-translations), including next-intl and react-i18next.

Specify the source language, target locales and the feature to change. Include validation messages, placeholders, accessible labels and metadata. Choose local or CDN delivery, and name who will review the result in the [Dashboard Translation Editor](/docs/platform/dashboard/guides/reviewing-translations).

## Connect General Translation's MCP server

General Translation's hosted [Model Context Protocol (MCP) server](/docs/overview/for-coding-agents#mcp) lets your coding agent inspect live project settings and manage translation context. The agent can look up your project's locales, read shared terminology, and update Glossary terms or Custom Prompts when the task requires it. This links the code changes to the translation rules your team maintains in General Translation.

The connection supports the translation workflow end to end, with tools for:

* Translating content, uploading source files, queuing translation jobs, checking status and downloading results.
* Publishing or unpublishing translations on the CDN.
* Discovering and creating projects, and creating scoped project API keys when authorised.
* Managing Context Groups, Glossary terms and Custom Prompts.

Give the agent the permissions it needs for the workflow you want it to carry out. Keep generated keys in a protected secret store, never in chat or browser code. Translation generation uses the service and is subject to its usage pricing; the CLI below handles the app's local extraction and translation sequence.

In **Cursor**, add this server entry to your project's `.cursor/mcp.json`, preserving any existing entries. See [Cursor's MCP set-up](https://cursor.com/docs/mcp) for configuration and authentication options.

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "generaltranslation": {
      "url": "https://api.gtx.dev/mcp"
    }
  }
}
```

In **Claude Code**, register the same server using its [HTTP transport](https://code.claude.com/docs/en/mcp):

```bash
claude mcp add --transport http generaltranslation https://api.gtx.dev/mcp
```

Complete the client's OAuth sign-in flow, or configure an API Key through its secret-header settings as described in the [MCP authentication guide](/docs/overview/for-coding-agents#mcp). Context Management requires Organisation Context access through OAuth or an Organisation key with the relevant Context permissions; project keys cannot access those tools.

Start with a concrete request: ‘Use the generaltranslation MCP server to list my projects and show the locale settings for the project we're localising.’ Then have the agent inspect the project's assigned Context Groups, which hold shared Glossary terms and Custom Prompts. It can apply those terms and instructions while preparing the feature, and update them when you've requested a terminology or style change.

Use the framework docs for code integration and the CLI for the extraction and translation steps below. The MCP connection gives the agent access to the live project and its context; the app still needs its SDK set-up, translated content and verification.

## Add a feature brief with acceptance criteria

Add this brief to the official set-up prompt. Replace the feature and locales with your own requirements; the example below uses English, Spanish and French.

```text
Internationalise the project-list feature in this application.
Use English as the source language and Spanish and French as target languages.
Include the heading, owner name, project count, search input, visible label,
placeholder, and language selector. Use locally bundled translations and
preserve existing routes and providers. Use the connected GT MCP server to
read project settings and assigned terminology when permitted. Report any
connection or permission gaps. Do not change shared context outside this task.
Verify counts 0, 1, and 2, a name containing punctuation, input labels and
placeholders, language switching, reload persistence, and the production build.
Check server-rendered content if this app uses SSR. Report the actual commands
and results, translation-review status, and anything untested. Source templates
are not completed translations. Limit changes to this feature and its setup.
Do not deploy or merge.
```

Keep project rules in the instruction mechanism that your agent reads. Cursor documents [project rules and AGENTS.md](https://cursor.com/docs/rules); Claude Code documents [CLAUDE.md and other project instructions](https://code.claude.com/docs/en/memory). Add the chosen library, source locale, translation command and required checks to your existing instructions. Avoid maintaining competing copies that can drift out of sync.

## Review a representative implementation

For a browser-only React app, the [React SPA Quickstart](/docs/react/react-spa-quickstart) configures `gt-react` before rendering. This example assumes that set-up is complete, with local output at `src/_gt/[locale].json`. It uses `gt-react@11.4.12` and the `gt@2.26.5` CLI.

The component below covers static copy, a dynamic value, plural forms and input text. Render it with a project count and an owner name from your 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 (
    <section>
      <T>
        <h1>Projects for <Var>{ownerName}</Var></h1>
        <p>
          <Plural
            n={count}
            one={<>You have <Num>{count}</Num> project.</>}
            other={<>You have <Num>{count}</Num> projects.</>}
          />
        </p>
      </T>
      <label>
        <T>Search projects</T>
        <input type='search' placeholder={gt('Search projects')} />
      </label>
    </section>
  );
}
```

[`<Var>`](/docs/react/reference/components/var) preserves the owner&#39;s name while the surrounding message is translated; its value is not sent to the translation API. [`<Plural>`](/docs/react/reference/components/plural) selects a branch using the locale&#39;s rules, and [`<Num>`](/docs/react/reference/components/num) formats the count. [`useGT`](/docs/react/reference/hooks/use-gt) returns the translation function directly. The visible label wraps the input, so the control has a label as well as a translated placeholder.

The `one` and `other` branches describe the English source. Target-language translations must represent their own plural forms; don&#39;t assume that testing English&#39;s singular/plural pair covers every language. See the [React pluralisation guide](/kb/how-to-handle-plurals-in-react).

In a React SPA, the documented [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) set-up loads translations before the app. Its [`LocaleSelector`](/docs/react/reference/components/locale-selector) saves the language choice in a cookie and reloads the page. Server-rendered frameworks have different set-up requirements; use the relevant quickstart instead.

## Produce translations before judging the result

For the local trial, run this from the configured app directory after adding the component:

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) creates source templates without calling the translation service. Supply translated text in the Spanish and French files, preserving the generated keys, variable markers and JSX structure. The existence of `es.json` does not mean it contains Spanish.

For service-generated translations, follow the [CLI authentication and project set-up](/docs/cli/quickstart), then use [`gt translate`](/docs/cli/reference/commands/translate). Authenticate with a CLI login or an API key, and configure the project ID separately; logging in alone does not select a project. For unattended CI, supply `GT_API_KEY` through the CI provider&#39;s secret settings, with permissions for the translation workflow. See the [credential configuration guide](/docs/cli/guides/configuring#credentials), and keep tooling keys out of browser code. Service usage charges apply.

General Translation translates the marked JSX along with its structure and any explicit context you provide. Add the [`context` prop](/docs/react/reference/components/t#context) for ambiguous copy, and apply the project&#39;s shared [Glossary terms and Custom Prompts](/docs/platform/dashboard/guides/defining-context-for-translations) to guide product terminology and tone. This gives translation production the same product rules that the coding agent reads through MCP.

With [locally bundled translations](/docs/react/guides/storing-translations), prepare the locale files before the production build. Keep manually maintained files in version control or your translation pipeline. Don&#39;t ignore the only copy of hand-edited translations as though it were disposable output.

## Verify the feature, then expand

Run [`gt validate`](/docs/cli/reference/commands/validate) to catch supported inline-translation errors before an API request, then have the agent report the observed results for each check below.

| Check                                   | Expected result                                                         |
| --------------------------------------- | ----------------------------------------------------------------------- |
| Select Spanish, then French             | Heading, count message, label and placeholder use the selected language |
| Reload after choosing a language        | The selected language persists according to the app&#39;s policy        |
| Try counts 0, 1 and 2                   | Each language uses its own plural rules; the number stays correct       |
| Use an owner such as O&#39;Connor       | The name remains intact in every language                               |
| Inspect the input&#39;s accessible name | It matches the translated visible label                                 |
| Run the production build and preview    | The same feature works with the files that will ship                    |

In the sample, [French zero and English zero use different plural categories](https://cldr.unicode.org/index/cldr-spec/plural-rules). Check that the rendered sentence uses the correct form and preserves the count.

Once the pattern works, expand one route or feature at a time. Reviewers can edit translations in the [Dashboard Translation Editor](/docs/platform/dashboard/guides/reviewing-translations). Inviting translators, PMs and in-country reviewers requires a Starter or Enterprise plan, and both plans include [unlimited users](https://generaltranslation.com/pricing). Enterprise adds translation approval. If your team edits the generated local files, opt in to [`gt save-local`](/docs/cli/reference/commands/save-local) to upload those changes for later reuse. See [reviewing AI translations](/kb/review-translations) for the review workflow.

## Keep localisation running after the agent session

Put [`gt translate` before the production build](/docs/cli/guides/generating-translations) to update translations when source copy changes. The incremental workflow reuses matching translations rather than regenerating every message on each run.

For ongoing work without driving your own coding assistant, General Translation&#39;s hosted agent, [Locadex](/docs/platform/locadex/guides/configuring-automations), can internationalise new UI, generate translations, and synchronise added or removed locales. Configure pull-request, push or manual triggers; changes arrive as pull requests. [Auto-merge](/docs/platform/locadex/guides/auto-merging-prs) is optional. A coding assistant can set up the integration, and Locadex can carry it forward into subsequent releases. Locadex requires a Starter or Enterprise plan, and its runs are billed by [usage](https://generaltranslation.com/pricing/usage). See the [automation reference](/docs/platform/locadex/reference/automations) for set-up, or [run translation in CI](/kb/translations-in-ci) with your own pipeline.

## Related questions

- [How do I add i18n to a Next.js App Router app?](https://generaltranslation.com/en-GB/kb/add-i18n-to-nextjs.mdx): Start with gt init to configure General Translation in a supported App Router project, then mark source content, generate translations and verify language switching. gt-next keeps copy in JSX with translation context; the CLI, Dashboard editor and Locadex handle generation, review and ongoing updates. This guide also shows the explicit local-file set-up.
- [Can I do i18n without translation files?](https://generaltranslation.com/en-GB/kb/i18n-without-translation-files.mdx): Yes. General Translation's gt-react and gt-next libraries do React and Next.js i18n with no translation keys and no JSON file per language to maintain. Copy stays inline in JSX inside the `<T>` component, and the gt translate command generates each language's translations in your build, with context from your code. Locadex can keep them up to date through pull requests.
- [How do I handle plurals in React?](https://generaltranslation.com/en-GB/kb/how-to-handle-plurals-in-react.mdx): Handle plurals in React by giving each language one sentence per plural form and picking it with that language's plural rules, since English has 2 forms, Russian has 4 and Arabic has 6. General Translation's `<Plural>` component in gt-react and gt-next takes your source forms, and General Translation generates the forms each target language needs.
- [What does the Locadex agent do?](https://generaltranslation.com/en-GB/kb/what-is-locadex.mdx): Locadex is General Translation's AI agent which internationalises your code and translates your content in your GitHub repository. Its automations run when a pull request is opened, when a commit is pushed, or when you start one, and every change arrives as a pull request.

## Previous and next questions

- Previous question: [How do I format numbers, dates and currencies for each locale?](https://generaltranslation.com/en-GB/kb/format-numbers-dates-currencies.mdx)
- Next question: [How do I keep translations up to date on every deploy?](https://generaltranslation.com/en-GB/kb/translations-in-ci.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/en-GB/kb/sitemap.md) for every article.