# General Translation Overview: Uso de agentes de programación URL: https://generaltranslation.com/es/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt 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 del 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, u obtén la misma guía directamente desde [`/AGENTS.md`](/AGENTS.md). ````markdown title="AGENTS.md" # General Translation — guía para agentes Instrucciones para agentes de programación con IA que añadan [General Translation](https://generaltranslation.com) a un proyecto. General Translation es un producto de localización full-stack: bibliotecas i18n de código abierto más una CLI que traducen una aplicación y su contenido a cualquier idioma. Sigue estas reglas al internacionalizar código o al configurar traducciones. ## Qué usar Elige el paquete que corresponda al stack: - **Next.js (App Router or Pages Router)** → `gt-next` - **React (SPA, p. ej. Vite)** → `gt-react` - **Vue 3** → `gt-vue` - **Servidor Node.js** → `gt-node` - **Cualquier entorno de ejecución JavaScript, o control de más bajo nivel** → `generaltranslation` (la biblioteca Core) - **Traducir archivos de contenido (JSON, MDX, YAML y más) o ejecutar traducciones en CI** → la CLI `gt` Todo esto es gratuito y de código abierto. Las bibliotecas funcionan con o sin una cuenta de General Translation; una clave de API habilita la traducción bajo demanda en desarrollo y la API de traducción alojada. ## Configuración Es preferible usar el asistente. Desde la raíz del proyecto, ejecuta: ```bash npx gt init ``` Instala la biblioteca adecuada y la CLI `gt`, configura el framework (para Next.js, añade `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 # o gt-react / gt-node / generaltranslation npm install -D gt ``` Luego crea `gt.config.json` en la raíz del proyecto: esta es la única fuente de verdad para los locales: ```json { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` - `defaultLocale` — el idioma en el que está escrito el código fuente. - `locales` — los idiomas a los que traducir. - `files.gt.output` — dónde escribe la CLI los archivos de traducción (`[locale]` se reemplaza por cada idioma). Añade este directorio a `.gitignore`; los archivos se generan. Define las credenciales de API como variables de entorno (en `.env.local` para Next.js, `.env` en los demás casos): ```bash GT_API_KEY="gtx-dev-..." # gtx-dev- en desarrollo, gtx-api- en producción/CI GT_PROJECT_ID="..." ``` Nunca hagas commit de `GT_API_KEY`, ni la expongas al navegador, ni le pongas el prefijo `NEXT_PUBLIC_`. ## Uso básico Envuelve el JSX visible para el usuario en ``. Escribe el texto original directamente: no se necesitan claves de traducción: ```tsx import { T } from 'gt-next'; // o 'gt-react' // Todo lo que está dentro de se traduce como una unidad

Welcome to my app

; ``` Usa `useGT()` para cadenas independientes (placeholders, `aria-label`, `alt`, etiquetas de botones). `useGT()` devuelve directamente la función de traducción: ```tsx import { useGT } from 'gt-next'; const gt = useGT(); // ✅ correcto // const { gt } = useGT(); // ❌ incorrecto — useGT devuelve la función, no un objeto ; ``` En componentes asíncronos del 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 `` para que no se traduzcan ni se envíen nunca a la API. Usa ``, `` y `` para valores que deban reformatearse pero no traducirse: ```tsx import { T, Var } from 'gt-next'; // Genera una sola traducción y mantiene el nombre sin cambios Hello, {name}! ; ``` 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 handlers 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 listas de locales por el código. ## 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 API de General Translation. Ejecútalo en CI **antes** de compilar para producción; añade `--save-local` solo cuando las ediciones locales deban sincronizarse primero. | | `npx gt generate` | Para crear plantillas de archivos de traducción y traducirlas manualmente (no se necesita clave de API). | | `npx gt api --spec` | Para inspeccionar el contrato OpenAPI incluido con la CLI instalada. | | `npx gt api ` | Para hacer una solicitud de API sin procesar y autenticada desde un script o la terminal. | | `npx gt project create --org-id --name --default-locale ` | Para crear un proyecto con una clave de organización. | | `npx gt project status ` | Para inspeccionar un trabajo de traducción o de generación de contexto del proyecto. | Añade la traducción a la compilación de producción para que las traducciones se mantengan actualizadas, por ejemplo: `"build": "npx gt translate && next build"`. ## Reglas — qué hacer y qué no Qué hacer: - Envuelve cada nuevo texto visible para el usuario en `` (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 texto nuevo se traduzca. - Mantén la lista de locales únicamente en `gt.config.json`. - Envuelve los valores dinámicos y privados en `` y añade `context` cuando una cadena sea ambigua. - Después de editar deliberadamente un archivo de traducción generado, ejecuta `npx gt save-local` antes de volver a descargar traducciones, o pasa `--save-local` en la siguiente ejecución de traducción. Qué no hacer: - No codifiques cadenas ya traducidas en el código fuente, ni añadas ramas `if`/`switch` por idioma: traduce el texto original en su lugar. - No edites los archivos de traducción generados sin sincronizar los cambios; una descarga posterior puede sobrescribir las ediciones no guardadas. - No hagas commit de `GT_API_KEY` ni la expongas al cliente. - No dupliques la configuración de locales fuera de `gt.config.json`. ## Enlaces - [`llms.txt`](/llms.txt) — punto de entrada curado a la documentación, legible por máquinas. - [`llms-index.txt`](/llms-index.txt) — índice exhaustivo de todas las páginas de la documentación. - [`llms-full.txt`](/llms-full.txt) — contenido completo de la documentación para herramientas que pueden cargar un contexto más amplio. - [Índice de React](/docs/react/llms.txt), [índice de la CLI](/docs/cli/llms.txt) e [índice de OpenAPI](/docs/platform/openapi/llms.txt) — puntos de entrada específicos para tareas habituales. - [`AGENTS.md`](/AGENTS.md) — esta guía lista para usar, en Markdown sin procesar. - [`openapi.yaml`](/openapi.yaml) — especificación canónica de la API de General Translation. - [`sitemap.md`](/sitemap.md) — índice en Markdown de todas las páginas de la documentación y entradas del blog. - [`sitemap.xml`](/sitemap.xml) — sitemap estándar de todas las páginas publicadas. - Guías rápidas: [React](/docs/react/react-quickstart), [Vue](/docs/vue/quickstart), [Node](/docs/node/quickstart), [biblioteca Core](/docs/platform/core/quickstart) y la [CLI](/docs/cli/quickstart). - [Conceptos clave](/docs/overview/key-concepts) — locales, contexto y contenido estático frente a dinámico. - Referencia de la CLI: [`gt api`](/docs/cli/reference/commands/api), [`gt project create`](/docs/cli/reference/commands/project-create) y [`gt project status`](/docs/cli/reference/commands/project-status). ```` ## Dirige a los agentes hacia 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 entry points legibles por máquinas en la raíz del sitio y bajo `/docs` en el host de la documentación: * [`llms.txt`](/llms.txt): un entry point curado al estilo [llmstxt.org](https://llmstxt.org/), con los Quickstarts principales e índices específicos. * [`llms-index.txt`](/llms-index.txt): el índice exhaustivo de enlaces de todas las páginas de documentación publicadas. * [`llms-full.txt`](/llms-full.txt): todo el contenido de la documentación en un único archivo, sin incluir la referencia de OpenAPI generada. * [`AGENTS.md`](/AGENTS.md): la guía lista para usar de arriba en Markdown raw. * [`sitemap.md`](/sitemap.md): un índice en Markdown de todas las páginas de documentación y entradas del blog. * [`sitemap.xml`](/sitemap.xml): el sitemap XML estándar de todas las páginas publicadas. Usa un índice acotado cuando el agente ya sepa qué parte del producto necesita: * [Overview](/docs/overview/llms.txt) * [Platform](/docs/platform/llms.txt), con índices específicos para [Dashboard](/docs/platform/dashboard/llms.txt), [Locadex](/docs/platform/locadex/llms.txt), [Core](/docs/platform/core/llms.txt) y [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) Para trabajar con la API, usa el [bundle de operaciones de OpenAPI](/docs/platform/openapi/llms-full.txt) o la especificación canónica [`openapi.yaml`](/openapi.yaml) en lugar de extraer datos de las páginas interactivas de endpoints. El host de la documentación también sirve los archivos de la raíz bajo `/docs`, incluidos `/docs/llms.txt`, `/docs/llms-index.txt` y `/docs/llms-full.txt`. Todas las páginas de la documentación están disponibles como **Markdown raw**: añade `.md` o `.mdx` a la URL de cualquier página para obtener el source limpio en lugar de analizar el HTML renderizado. Los índices generados y los metadatos de descubrimiento usan `.mdx`, por ejemplo `/docs/cli/quickstart.mdx`. 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 source en las herramientas que admitan la indexación de documentación. ## Servidor MCP [#mcp] Usa el servidor [Model Context Protocol](https://modelcontextprotocol.io) (MCP) alojado en `https://api.gtx.dev/mcp` para obtener información actualizada del Project. Utiliza streamable HTTP. El servidor alojado también proporciona [herramientas MCP de Google Drive](/docs/integrations/google-drive/reference/mcp-tools) para encontrar Projects conectados, traducir Google Docs y Google Slides, y sondear el progreso de las copias traducidas. Añade la connection al config file de MCP de tu herramienta (por ejemplo, `.mcp.json`). Los nombres de transporte y los campos de configuración pueden variar según el cliente: ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### Autentícate con la API remota Conéctate mediante el flujo de inicio de sesión OAuth de tu cliente MCP, o configura `Authorization: Bearer ` usando sus ajustes de cabecera secreta. Las conexiones con clave de API aceptan claves de Project de producción (`gtx-api-`), claves de Project de desarrollo (`gtx-dev-`) y Organization keys (`gtx-org-`). Cada herramienta decide si se permiten las development keys; la runtime translation y las [herramientas MCP de Google Drive](/docs/integrations/google-drive/reference/mcp-tools) las aceptan, mientras que otras herramientas pueden rechazarlas. El servidor publica sus metadatos de recurso protegido y de servidor de autorización. Un cliente compatible con OAuth se registra dinámicamente, utiliza el flujo Authorization Code con Proof Key for Code Exchange (PKCE) y abre la pantalla de consentimiento del Dashboard. Solicita `openid` y `profile` para los claims de identity, y solicita `offline_access` cuando el cliente necesite un token de actualización. Usa `list_projects` para encontrar un Project ID y luego pásalo como `projectId` a las herramientas del Project. Una clave de Project de producción puede omitir `projectId` para usar su propio Project. Una vez conectado, pídele a tu agente que use el servidor MCP `generaltranslation`. Prueba con: «Lista mis Projects y muestra la configuración regional de uno de ellos». ## 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 "use la herramienta `generaltranslation`". Añade la documentación como fuente o menciona `/llms.txt` en tu prompt. * **Claude Code** — lee automáticamente un `CLAUDE.md` en el root, así que copia la [guía del agente](#agent-guide) en el `CLAUDE.md` de tu proyecto. Registra el servidor MCP y pídele que "use el servidor MCP de `generaltranslation`". * **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 [``](/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 prompts personalizados) que escribe el agente, la configuración regional (`defaultLocale` y `locales`) y que los valores dinámicos o privados estén envueltos en [``](/docs/react/reference/components/var). * **Nunca dejes que el agente haga:** editar los archivos de traducción generados sin sincronizar los cambios ni codificar de forma fija cadenas ya traducidas en lugar de traducir el texto fuente con la CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.