# General Translation Overview: Uso de agentes de programación
URL: https://generaltranslation.com/es/docs/overview/for-coding-agents.mdx
---

title: Uso de agentes de programación
description: Cómo usar agentes de programación con IA y LLMs con General Translation, indicándoles la documentación legible por máquinas, el servidor MCP y nuestra guía de agente lista para usar.

---

General Translation está diseñado para funcionar con agentes de programación con IA y LLMs. Las bibliotecas son de código abierto, la configuración es predecible y la documentación se publica en formatos legibles por máquinas. Un agente como Cursor, Claude Code o Copilot puede añadir y ejecutar General Translation por ti con un contexto preciso y actualizado.

*Para una localización totalmente automatizada que abra pull requests por sí sola, usa nuestro agente dedicado [Locadex](/docs/platform/locadex/quickstart) en lugar de usar tu propio agente.*

## Guía del agente lista para usar [#agent-guide]

Dale a tu agente todo lo que necesita con una sola pega. Copia la guía de abajo en un archivo `AGENTS.md` (o `CLAUDE.md`, una regla de Cursor o el archivo de instrucciones de tu herramienta) en la raíz de tu proyecto, y tu agente añadirá y ejecutará General Translation correctamente. Usa el botón de copiar en la esquina superior derecha del bloque.

````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, 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. |
| `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) — índice de documentación breve y legible por máquinas.
- [`llms-full.txt`](/llms-full.txt) — contenido completo de la documentación para herramientas que pueden cargar un contexto más amplio.
- [`sitemap.xml`](/sitemap.xml) — mapa de todas las páginas publicadas.
- Quickstarts: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [biblioteca Core](/docs/platform/core/quickstart) y el [CLI](/docs/cli/quickstart).
- [Key concepts](/docs/overview/key-concepts) — locales, context, and static vs. dynamic content.
````

## Dirige los agentes a la documentación [#point-agents]

Dale a tu agente acceso directo a la documentación para que sus respuestas sigan siendo precisas. General Translation publica varios puntos de entrada legibles por máquinas en la raíz del sitio y en `/docs` en el host de la documentación:

* [`llms.txt`](/llms.txt) — un índice breve de la documentación, al estilo de [llmstxt.org](https://llmstxt.org/).
* [`llms-full.txt`](/llms-full.txt) — todo el contenido de la documentación en un solo archivo, excluida la referencia de OpenAPI generada.
* [`sitemap.xml`](/sitemap.xml) — un mapa legible por máquinas de cada página publicada.

El host de la documentación también sirve estos archivos en `/docs/llms.txt` y `/docs/llms-full.txt`. Cada página de la documentación también está disponible como **Markdown sin procesar**: añade `.md` o `.mdx` a cualquier URL de página (por ejemplo, `/docs/cli/quickstart.mdx`) para obtener el contenido fuente limpio en lugar de analizar el HTML renderizado.

Para añadir la documentación como contexto, pega una URL de la documentación o el enlace de `llms.txt` en el contexto de tu agente, o añade la documentación como fuente en herramientas que admitan la indexación de documentación.

## Servidor MCP [#mcp]

General Translation ofrece un servidor [Model Context Protocol](https://modelcontextprotocol.io) (MCP) que permite a los agentes consultar la documentación directamente. Está disponible en dos formas:

* **Local (stdio)** — el paquete npm publicado [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp), que se ejecuta en tu máquina con `npx`. Es la mejor opción para herramientas que mantienen una conexión persistente, como Cursor y Claude Code.
* **Remoto (HTTP/SSE)** — un endpoint alojado en `https://mcp.gtx.dev`. Usa el endpoint SSE solo si tu herramienta no admite Streamable HTTP.

Configura la conexión con el transporte que admita tu herramienta. La estructura de la configuración es idéntica en todas las herramientas: agrégala al archivo de configuración MCP de tu herramienta (por ejemplo, `.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>

Una vez conectado, pídele a tu agente que use el servidor MCP `generaltranslation`. *Ejemplo: &quot;Usa el servidor MCP `generaltranslation` para explicar cómo usar un componente [`<T>`](/docs/react/reference/components/t).&quot;*

## Consejos específicos para cada editor [#editor-tips]

La mayor parte de la configuración es la misma en todos los agentes; estos son los pocos puntos en los que las instrucciones cambian.

* **Cursor** — registra el servidor MCP y luego pídele que &quot;use la herramienta `generaltranslation`&quot;. Añade la documentación como fuente o menciona `/llms.txt` en tu prompt.
* **Claude Code** — lee automáticamente un `AGENTS.md` en el root, así que basta con poner la [guía del agente](#agent-guide) en el `AGENTS.md` de tu proyecto para dejarlo listo. Registra el servidor MCP y pídele que &quot;use el servidor MCP de `generaltranslation`&quot;.
* **Copilot** — coloca las instrucciones para todo el repo en tu archivo de instrucciones (por ejemplo, `.github/copilot-instructions.md`) y menciona allí `/llms.txt` de la documentación.

## Prácticas recomendadas [#best-practices]

Los agentes son fiables para las tareas mecánicas de i18n, pero la calidad de la traducción y la configuración siguen requiriendo supervisión humana. Usa esta división:

* **Deja en manos del agente:** envolver el texto visible para el usuario en [`<T>`](/docs/react/reference/components/t), agregar [`useGT()`](/docs/react/reference/hooks/use-gt) para cadenas independientes, preparar `gt.config.json` y ejecutar [`npx gt init`](/docs/cli/reference/commands/init).
* **Verifica a mano:** el [contexto de traducción](/docs/overview/key-concepts#context) (glosario y Directives) que escribe el agente, la configuración regional (`defaultLocale` y `locales`) y que los valores dinámicos o privados estén envueltos en [`<Var>`](/docs/react/reference/components/var).
* **Nunca dejes que el agente haga:** editar manualmente los archivos de traducción generados ni codificar de forma fija cadenas ya traducidas en lugar de traducir el texto fuente con la CLI.