# 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

Instrucciones para agentes de codificación con IA que integran [General Translation](https://generaltranslation.com) en un proyecto. General Translation es un producto de localización integral: bibliotecas i18n de código abierto más un CLI que traducen una aplicación y su contenido a cualquier idioma. Sigue estas reglas al internacionalizar código o configurar traducciones.

## Qué usar

Elige el paquete que corresponda a tu plataforma:

- **Next.js (App Router o Pages Router)** → `gt-next`
- **React (SPA, p. ej. Vite)** → `gt-react`
- **Servidor Node.js** → `gt-node`
- **Cualquier runtime de JavaScript, o control de bajo nivel** → `generaltranslation` (la biblioteca Core)
- **Traducir archivos de contenido (JSON, MDX, YAML y más) o ejecutar traducciones en CI** → el CLI `gt`

Todos son gratuitos y de código abierto. Las bibliotecas funcionan con o sin una cuenta de General Translation; una API Key habilita la traducción on-demand en desarrollo y la translation API alojada.

## Configuración

Se recomienda usar el asistente. Desde el project root, ejecuta:

```bash
npx gt init
```

Instala la biblioteca adecuada y el CLI `gt`, configura el framework (para Next.js, agrega `withGTConfig` y `GTProvider`), crea `gt.config.json` y genera las credenciales de API.

Para una configuración manual, instala los paquetes tú mismo:

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

Luego crea `gt.config.json` en el project root — esta es la fuente única de verdad para los locales:

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": { "gt": { "output": "public/_gt/[locale].json" } }
}
```

- `defaultLocale` — el idioma en que está escrito el source.
- `locales` — los idiomas a los que se traducirá.
- `files.gt.output` — dónde escribe el CLI los translation files (`[locale]` se reemplaza por cada idioma). Agrega este directorio a `.gitignore`; los archivos se generan automáticamente.

Configura las credenciales de API como variables de entorno (en `.env.local` para Next.js, `.env` en otros casos):

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

Nunca hagas commit de `GT_API_KEY`, la expongas al navegador ni le agregues el prefijo `NEXT_PUBLIC_`.

## Uso básico

Envuelve el JSX visible para el usuario en `<T>`. Escribe el texto fuente directamente — no se necesitan keys de traducción:

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

// Todo lo que está dentro de <T> se traduce como una unidad
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Usa `useGT()` para cadenas independientes (placeholders, `aria-label`, `alt`, etiquetas de botones). `useGT()` devuelve la función de traducción directamente:

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ correcto
// const { gt } = useGT(); // ❌ incorrecto — useGT devuelve la función, no un objeto

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

En componentes asíncronos de App Router, usa `getGT` en su lugar. `gt-next/server` no funciona con el Pages Router:

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

Envuelve los valores dinámicos o privados (nombres, correos electrónicos, IDs) en `<Var>` para que no se traduzcan ni se envíen a la API. Usa `<Currency>`, `<DateTime>` y `<Num>` para valores que deben reformatearse pero no traducirse:

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

// Genera una sola traducción, mantiene el nombre sin cambios
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

Para servidores Node.js, inicializa una vez y resuelve las traducciones por solicitud:

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// envuelve los manejadores de solicitud en withGT(locale, ...); luego usa `const gt = await getGT()` dentro de ellos
```

Mantén toda la configuración de locales en `gt.config.json` — no disperses las listas de locales por el codebase.

## Comandos

| Comando | Cuándo ejecutarlo |
| --- | --- |
| `npx gt init` | Una vez, para configurar un proyecto (instala dependencias, configura el framework, crea `gt.config.json`, genera credenciales). |
| `npx gt configure` | Para crear o actualizar `gt.config.json` (locales y archivos) sin el asistente completo. |
| `npx gt auth` | Para generar o renovar las credenciales de API. |
| `npx gt translate` | Para traducir el proyecto mediante la General Translation API. Ejecútalo en CI **antes** de compilar para producción. |
| `npx gt generate` | Para crear plantillas de translation files y traducirlas manualmente (no se necesita API key). |

Agrega la traducción a la compilación de producción para mantener las traducciones actualizadas, por ejemplo: `"build": "npx gt translate && next build"`.

## Reglas — qué hacer y qué no hacer

Hacer:

- Envuelve cada nuevo texto visible para el usuario en `<T>` (o `useGT()`/`getGT()` para cadenas independientes) a medida que lo escribes.
- Ejecuta `npx gt translate` antes de hacer commit o compilar para producción, para que el nuevo texto quede traducido.
- Mantén la lista de locales únicamente en `gt.config.json`.
- Envuelve los valores dinámicos y privados en `<Var>`, y agrega `context` cuando una cadena sea ambigua.

No hacer:

- Codificar de forma fija cadenas ya traducidas en el source, ni agregar ramas `if`/`switch` por idioma — traduce el texto fuente en su lugar.
- Editar manualmente los translation files generados (el CLI los sobreescribe).
- Hacer commit de `GT_API_KEY` ni exponerla al cliente.
- Duplicar la configuración de locales fuera de `gt.config.json`.

## Enlaces

- [`llms.txt`](/llms.txt) — índice de documentación breve y legible por máquinas.
- [`sitemap.md`](/sitemap.md) — mapa de todas las páginas de la documentación.
- Quickstarts: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [biblioteca Core](/docs/platform/core/quickstart) y el [CLI](/docs/cli/quickstart).
- [Conceptos clave](/docs/overview/key-concepts) — locales, context y contenido estático vs. dinámico.
````

## 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áquina en la raíz del sitio:

* [`llms.txt`](/llms.txt) — un índice breve de la documentación, al estilo de [llmstxt.org](https://llmstxt.org/).
* [`sitemap.md`](/sitemap.md) — un mapa enlazado de todas las páginas en orden de navegación.

Cada página de la documentación también está disponible como **Markdown sin procesar**: añade `.md` a cualquier URL de página (por ejemplo, `/docs/cli/quickstart.md`) 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>`, agregar [`useGT()`](/docs/react/reference/hooks/use-gt) para cadenas independientes, preparar `gt.config.json` y ejecutar `npx gt 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.