# General Translation Knowledge Base: ¿Cómo internacionalizo una aplicación con Cursor o Claude Code? URL: https://generaltranslation.com/es/kb/ai-agent-i18n-setup.mdx Docs index: https://generaltranslation.com/llms.txt Description: Empieza con el prompt Setup for Agents de General Translation en Cursor o Claude Code, elige una funcionalidad y los idiomas de destino, y deja que el agente implemente y verifique el resultado. El inicio de sesión desde el navegador, la documentación legible por máquinas y las herramientas MCP enlazan la configuración inicial con la traducción y la revisión. Usa Locadex para automatizar la localización continua mediante pull requests. Category: Internacionalización Last updated: 2026-10-21 Authors: Kevin Liu, Kevin Wu Published: 2026-10-21 «Traduce mi aplicación al español» deja varias decisiones en el aire. ¿Debe el agente conservar la biblioteca existente? ¿Necesita el español su propia URL? ¿Quién traducirá los textos nuevos cuando termine esta sesión? Define esos límites antes de pedirle que modifique la aplicación. General Translation ofrece un prompt de configuración inicial, mantenido y actualizado, que guía a un agente de programación por la inspección del proyecto, la integración, la traducción y la verificación. Empieza con una sola funcionalidad que funcione de principio a fin y, después, aplica el patrón ya verificado en toda la base de código. ## 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 s) 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. ## Empieza con Setup for Agents Usa **Setup for Agents** en generaltranslation.com o proporciona a Cursor o Claude Code el [prompt oficial para agentes](https://generaltranslation.com/agent-prompt.md). Este prompt indica al agente que inspeccione tu proyecto y siga las instrucciones vigentes del framework. En los proyectos compatibles, [`gt init`](/docs/cli/reference/commands/init) ofrece una configuración experimental del framework; después, el agente revisa la integración generada, marca el contenido, genera las traducciones y verifica la aplicación. Para acceder al servicio en local, [`gt login`](/docs/cli/reference/commands/login) te permite aprobar el inicio de sesión desde el navegador en lugar de pegar una clave de API en el chat. Aun así, la CLI necesita que el proyecto correspondiente esté seleccionado o configurado. Las opciones de configuración inicial permiten responder a las preguntas del asistente sin una terminal interactiva, pero el primer inicio de sesión sigue requiriendo tu aprobación. Para compilaciones desatendidas, usa credenciales con ámbito limitado guardadas en el almacén de secretos de tu CI. El agente puede descubrir la documentación a través de [`llms.txt`](https://generaltranslation.com/llms.txt), obtener el origen limpio añadiendo `.mdx` a cualquier URL de la documentación y consultar la [especificación OpenAPI](https://generaltranslation.com/openapi.yaml). La [guía para agentes de programación](/docs/overview/for-coding-agents) incluye instrucciones de proyecto reutilizables. Estos recursos se mantienen al día, de modo que la configuración inicial siempre se ajusta a las API actuales del producto. El [artículo sobre el diseño de la documentación](/blog/rewriting-our-docs) explica cómo funcionan estas superficies de descubrimiento. ## Asigna al agente una tarea acotada Pídele que revise el framework, las versiones instaladas, el modelo de renderizado, las rutas, la configuración de i18n existente y los scripts de compilación. Si la aplicación ya usa una biblioteca de i18n, consérvala, salvo que la migración forme parte de la tarea. La CLI de GT puede [traducir catálogos existentes compatibles](/docs/cli/guides/generating-translations), como los de next-intl y react-i18next. Especifica el idioma de origen, las configuraciones regionales de destino y la funcionalidad que se va a modificar. Incluye los mensajes de validación, los marcadores de posición, las etiquetas de accesibilidad y los metadatos. Elige entre entrega local o mediante CDN, e indica quién revisará el resultado en el [Editor de Traducciones del panel de control](/docs/platform/dashboard/guides/reviewing-translations). ## Conecta el servidor MCP de General Translation El [servidor de Model Context Protocol (MCP)](/docs/overview/for-coding-agents#mcp) alojado por General Translation permite que tu agente de programación consulte la configuración del proyecto en tiempo real y gestione el contexto de traducción. El agente puede consultar las configuraciones regionales de tu proyecto, leer la terminología compartida y actualizar los términos del glosario o los prompts personalizados cuando la tarea lo requiera. Así, los cambios en el código quedan alineados con las reglas de traducción que tu equipo mantiene en General Translation. La conexión cubre el flujo de trabajo de traducción de principio a fin mediante herramientas para: * Traducir contenido, subir archivos de origen, poner en cola tareas de traducción, comprobar su estado y descargar los resultados. * Publicar traducciones en la CDN o retirarlas de publicación. * Descubrir y crear proyectos, así como crear claves de API de proyecto con ámbito limitado, si se cuenta con autorización. * Gestionar grupos de contexto, términos del glosario y prompts personalizados. Concede al agente los permisos que necesite para el flujo de trabajo que quieras que realice. Guarda las claves generadas en un almacén de secretos protegido, nunca en el chat ni en código del navegador. La generación de traducciones usa el servicio y está sujeta a sus precios por uso; la CLI que se describe a continuación se encarga de la secuencia local de extracción y traducción de la aplicación. En **Cursor**, añade esta entrada de servidor al archivo `.cursor/mcp.json` de tu proyecto, sin eliminar las entradas existentes. Consulta la [configuración de MCP de Cursor](https://cursor.com/docs/mcp) para ver las opciones de configuración y autenticación. ```json title=".cursor/mcp.json" { "mcpServers": { "generaltranslation": { "url": "https://api.gtx.dev/mcp" } } } ``` En **Claude Code**, registra el mismo servidor con su [transporte HTTP](https://code.claude.com/docs/en/mcp): ```bash claude mcp add --transport http generaltranslation https://api.gtx.dev/mcp ``` Completa el flujo de inicio de sesión OAuth del cliente o configura una clave de API mediante sus ajustes de cabecera secreta, tal como se describe en la [guía de autenticación de MCP](/docs/overview/for-coding-agents#mcp). La gestión de contexto requiere acceso al contexto a nivel de organización, ya sea mediante OAuth o mediante una clave de organización con los permisos de contexto correspondientes; las claves de proyecto no pueden acceder a esas herramientas. Empieza con una petición concreta: “Usa el servidor MCP de generaltranslation para listar mis proyectos y mostrar la configuración regional del proyecto que estamos localizando”. Después, pide al agente que revise los grupos de contexto asignados al proyecto, que contienen los términos compartidos del glosario y los prompts personalizados. El agente puede aplicar esos términos e instrucciones mientras prepara la funcionalidad, y actualizarlos cuando le pidas un cambio de terminología o de estilo. Consulta la documentación del framework para integrar el código y usa la CLI para los pasos de extracción y traducción que se describen a continuación. La conexión MCP da al agente acceso al proyecto activo y a su contexto, pero la aplicación sigue necesitando la configuración inicial del SDK, el contenido traducido y la verificación. ## Agrega una descripción de la funcionalidad con criterios de aceptación Agrega esta descripción al prompt oficial de configuración inicial. Sustituye la funcionalidad y las configuraciones regionales por las que necesites; el siguiente ejemplo usa inglés, español y francés. ```text Internacionaliza la funcionalidad project-list de esta aplicación. Usa el inglés como idioma de origen y el español y el francés como idiomas de destino. Incluye el encabezado, el nombre del propietario, el recuento de proyectos, el campo de búsqueda, la etiqueta visible, el marcador de posición y el selector de idioma. Usa traducciones empaquetadas localmente y conserva las rutas y los proveedores existentes. Usa el servidor MCP de GT conectado para leer la configuración del proyecto y la terminología asignada, si tienes permiso. Informa de cualquier problema de conexión o falta de permisos. No modifiques el contexto compartido fuera de esta tarea. Verifica los recuentos 0, 1 y 2, un nombre que contenga signos de puntuación, las etiquetas y marcadores de posición de los campos, el cambio de idioma, la persistencia tras recargar y la compilación de producción. Comprueba el contenido server-rendered si esta aplicación usa SSR. Informa de los comandos ejecutados y sus resultados, el estado de la revisión de traducciones y todo lo que no se haya probado. Las plantillas de origen no son traducciones completadas. Limita los cambios a esta funcionalidad y su configuración inicial. No despliegues ni fusiones. ``` Mantén las reglas del proyecto en el mecanismo de instrucciones que lee tu agente. Cursor documenta las [reglas de proyecto y AGENTS.md](https://cursor.com/docs/rules); Claude Code documenta [CLAUDE.md y otras instrucciones de proyecto](https://code.claude.com/docs/en/memory). Añade a tus instrucciones existentes la biblioteca elegida, la configuración regional de origen, el comando de traducción y las comprobaciones obligatorias. Evita mantener varias copias en paralelo que puedan acabar desincronizándose. ## Revisar una implementación representativa Para una aplicación de React que se ejecuta solo en el navegador, la [Guía de inicio rápido para una SPA de React](/docs/react/react-spa-quickstart) configura `gt-react` antes de renderizar. Este ejemplo da por hecho que ya completaste esa configuración inicial y que la salida local se encuentra en `src/_gt/[locale].json`. Utiliza `gt-react@11.4.12` y la CLI `gt@2.26.5`. El siguiente componente incluye texto estático, un valor dinámico, formas plurales y texto de entrada. Renderízalo con un número de proyectos y el nombre de un propietario obtenidos de tu aplicación. ```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 (

Projects for {ownerName}

You have {count} project.} other={<>You have {count} projects.} />

); } ``` [``](/docs/react/reference/components/var) conserva el nombre del propietario mientras se traduce el mensaje que lo rodea; su valor no se envía a la API de traducción. [``](/docs/react/reference/components/plural) selecciona una rama según las reglas de la configuración regional y [``](/docs/react/reference/components/num) da formato al recuento. [`useGT`](/docs/react/reference/hooks/use-gt) devuelve directamente la función de traducción. La etiqueta visible envuelve el campo de entrada, de modo que el control cuenta con una etiqueta además de un marcador de posición traducido. Las ramas `one` y `other` describen el texto de origen en inglés. Las traducciones a cada idioma de destino deben reflejar sus propias formas plurales; no des por hecho que probar el par singular/plural del inglés cubre todos los idiomas. Consulta la [guía de pluralización en React](/kb/how-to-handle-plurals-in-react). En una SPA de React, la configuración inicial documentada de [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) carga las traducciones antes que la aplicación. Su [`LocaleSelector`](/docs/react/reference/components/locale-selector) guarda el idioma elegido en una cookie y recarga la página. Los frameworks server-rendered tienen requisitos de configuración inicial distintos; consulta su propia guía de inicio rápido. ## Genera las traducciones antes de evaluar el resultado Para la prueba local, después de añadir el componente, ejecuta lo siguiente desde el directorio de la app configurado: ```bash npx gt generate ``` [`gt generate`](/docs/cli/reference/commands/generate) crea plantillas de origen sin llamar al servicio de traducción. Añade tú mismo el texto traducido en los archivos de español y francés, conservando las claves generadas, los marcadores de variables y la estructura JSX. Que exista `es.json` no significa que contenga texto en español. Para obtener traducciones generadas por el servicio, sigue la [autenticación y configuración inicial del proyecto con la CLI](/docs/cli/quickstart) y luego usa [`gt translate`](/docs/cli/reference/commands/translate). Autentícate iniciando sesión en la CLI o con una clave de API, y configura el ID del proyecto por separado: iniciar sesión no selecciona ningún proyecto. Para CI desatendida, proporciona `GT_API_KEY` a través de la configuración de secretos de tu proveedor de CI, con permisos para el flujo de trabajo de traducción. Consulta la [guía de configuración de credenciales](/docs/cli/guides/configuring#credentials) y mantén las claves de herramientas fuera del código del navegador. El uso del servicio se factura. General Translation traduce el JSX marcado junto con su estructura y cualquier contexto explícito que proporciones. Añade la [prop `context`](/docs/react/reference/components/t#context) para textos ambiguos y aplica los [términos del glosario y prompts personalizados](/docs/platform/dashboard/guides/defining-context-for-translations) compartidos del proyecto para orientar la terminología y el tono del producto. Así, la generación de traducciones sigue las mismas reglas de producto que el agente de programación lee a través de MCP. Con [traducciones empaquetadas localmente](/docs/react/guides/storing-translations), prepara los archivos de configuración regional antes de la compilación de producción. Conserva los archivos mantenidos manualmente en el control de versiones o en tu flujo de traducción. No ignores la única copia de unas traducciones editadas a mano como si fuera un resultado desechable. ## Verifica la funcionalidad y luego amplíala Ejecuta [`gt validate`](/docs/cli/reference/commands/validate) para detectar los errores de traducción inline compatibles antes de enviar una solicitud a la API y, después, pide al agente que informe de los resultados observados en cada una de las siguientes comprobaciones. | Comprobación | Resultado esperado | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | Selecciona español y luego francés | El encabezado, el mensaje de recuento, la etiqueta y el marcador de posición se muestran en el idioma seleccionado | | Recarga la página después de elegir un idioma | El idioma seleccionado se conserva según la política de la aplicación | | Prueba con los recuentos 0, 1 y 2 | Cada idioma aplica sus propias reglas de plural y el número se mantiene correcto | | Usa un propietario como O'Connor | El nombre se mantiene intacto en todos los idiomas | | Inspecciona el nombre accesible del campo de entrada | Coincide con la etiqueta visible traducida | | Ejecuta la compilación de producción y la vista previa | La funcionalidad se comporta igual con los archivos que se van a publicar | En el ejemplo, [el cero en francés y el cero en inglés pertenecen a categorías de plural diferentes](https://cldr.unicode.org/index/cldr-spec/plural-rules). Comprueba que la oración renderizada use la forma correcta y conserve el recuento. Cuando el patrón funcione, amplíalo de ruta en ruta o de funcionalidad en funcionalidad. Los revisores pueden editar las traducciones en el [Editor de Traducciones del panel de control](/docs/platform/dashboard/guides/reviewing-translations). Para invitar a traductores, PM y revisores locales se necesita un plan Starter o un Plan empresarial; ambos incluyen [usuarios ilimitados](https://generaltranslation.com/pricing). El Plan empresarial añade además la aprobación de traducciones. Si tu equipo edita los archivos locales generados, activa [`gt save-local`](/docs/cli/reference/commands/save-local) para subir esos cambios y reutilizarlos más adelante. Consulta [revisar traducciones de IA](/kb/review-translations) para conocer el flujo de trabajo de revisión. ## Mantén la localización en marcha después de la sesión del agente Añade [`gt translate` antes de la compilación de producción](/docs/cli/guides/generating-translations) para actualizar las traducciones cada vez que cambie el texto de origen. El flujo de trabajo incremental reutiliza las traducciones coincidentes en lugar de volver a generar todos los mensajes en cada ejecución. Si quieres mantener el trabajo continuo sin tener que dirigir tu propio asistente de programación, el agente alojado de General Translation, [Locadex](/docs/platform/locadex/guides/configuring-automations), puede internacionalizar la nueva UI, generar traducciones y sincronizar las configuraciones regionales que se añadan o eliminen. Configura activadores por pull request, por push o manuales; los cambios llegan a través de pull requests. El [auto-merge](/docs/platform/locadex/guides/auto-merging-prs) es opcional. Un asistente de programación puede establecer la integración y Locadex puede mantenerla en los lanzamientos posteriores. Locadex requiere un plan Starter o un Plan empresarial, y sus ejecuciones se facturan según el [uso](https://generaltranslation.com/pricing/usage). Consulta la [referencia de automatizaciones](/docs/platform/locadex/reference/automations) para la configuración inicial, o [ejecuta la traducción en CI](/kb/translations-in-ci) con tu propio flujo. ## Related questions - [¿Cómo agrego i18n a una aplicación de Next.js con App Router?](https://generaltranslation.com/es/kb/add-i18n-to-nextjs.mdx): Empieza con gt init para configurar General Translation en un proyecto compatible con App Router; luego marca el contenido de origen, genera las traducciones y verifica el cambio de idioma. gt-next mantiene el texto en JSX junto con el contexto de traducción; la CLI, el editor del panel de control y Locadex se encargan de la generación, la revisión y las actualizaciones continuas. Esta guía también muestra la configuración inicial explícita con archivos locales. - [¿Puedo hacer i18n sin archivos de traducción?](https://generaltranslation.com/es/kb/i18n-without-translation-files.mdx): Sí. Las bibliotecas gt-react y gt-next de General Translation permiten hacer i18n en React y Next.js sin claves de traducción y sin tener que mantener un archivo JSON por idioma. El texto permanece inline en JSX dentro del componente ``, y el comando gt translate genera las traducciones de cada idioma durante la compilación, con contexto extraído de tu código. Locadex puede mantenerlas al día mediante pull requests. - [¿Cómo gestiono los plurales en React?](https://generaltranslation.com/es/kb/how-to-handle-plurals-in-react.mdx): Para gestionar los plurales en React, asigna a cada idioma una oración por cada forma plural y selecciónala con las reglas de plural de ese idioma, ya que el inglés tiene 2 formas, el ruso tiene 4 y el árabe tiene 6. El componente `` de General Translation en gt-react y gt-next recibe tus formas de origen, y General Translation genera las formas que necesita cada idioma de destino. - [¿Qué hace el agente Locadex?](https://generaltranslation.com/es/kb/what-is-locadex.mdx): Locadex es el agente de IA de General Translation que internacionaliza tu código y traduce tu contenido en tu repositorio de GitHub. Sus automatizaciones se ejecutan cuando se abre un pull request, cuando se hace push de un commit o cuando tú las inicias, y cada cambio llega como un pull request. ## Previous and next questions - Previous question: [¿Cómo doy formato a números, fechas y monedas para cada configuración regional?](https://generaltranslation.com/es/kb/format-numbers-dates-currencies.mdx) - Next question: [¿Cómo mantengo las traducciones actualizadas en cada despliegue?](https://generaltranslation.com/es/kb/translations-in-ci.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.