# 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 el prompt inicial, 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.* ## Prompt inicial [#start-prompt] El siguiente prompt inicia una sesión de agente que añade General Translation a tu Project: el agente lee el punto de entrada de la documentación, inicia sesión con [`gt login`](/docs/cli/reference/commands/login), selecciona un Project, implementa una primera traducción y la verifica. Un agente trabaja con la plataforma de General Translation a través de [`gt login`](/docs/cli/reference/commands/login), por eso el prompt empieza con este comando en lugar de pedirte una API Key. El botón **Setup for Agents** de [generaltranslation.com](https://generaltranslation.com) copia exactamente este texto, que también se sirve sin procesar en [`/agent-prompt.md`](/agent-prompt.md). El comando [`init`](/docs/cli/reference/commands/init) que indica el prompt se verificó con `gt` 2.24.0 en un Project `create-next-app` recién creado: no hace ninguna pregunta, instala `gt-next`, añade [`GTProvider`](/docs/react/reference/components/gt-provider) al layout raíz y `withGTConfig` a `next.config.ts`, crea `loadTranslations.js` y `gt.config.json`, y termina con un evento de éxito. ````markdown title="agent-prompt.md" # Get started with General Translation I landed on https://generaltranslation.com and clicked "Setup for Agents". Help me add General Translation to my app, website, or content, and get a real translation working. Inspect the project you have access to, choose the appropriate integration with me, and implement it. Continue through setup, translation, and verification rather than stopping at a plan. ## About General Translation General Translation (GT) combines open-source internationalization libraries, a translation CLI, and a hosted translation platform. Source content stays in your code or content files. The libraries render translations and format locale-sensitive values; the platform generates and manages translations. Locadex is an optional hosted agent that connects to GitHub and maintains localization through pull requests. - Website: https://generaltranslation.com - Dashboard: https://dash.generaltranslation.com - Open-source libraries and CLI: https://github.com/generaltranslation/gt - Documentation entry point: https://generaltranslation.com/llms.txt - Complete documentation index: https://generaltranslation.com/llms-index.txt - API specification: https://generaltranslation.com/openapi.yaml Fetch the documentation entry point first, then the quickstart and references relevant to this project. Documentation pages are available as raw Markdown by appending `.mdx` to the page URL. Use the complete index when you need a page that is not in the curated index. Read current docs and installed command help instead of guessing APIs, flags, or framework setup. `gt auth` is not a command in current releases; use `gt login`. `gt generate` writes source templates without calling the API and is registered when the CLI detects `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, `gt-node`, `gt-vue`, `gt-flask`, or `gt-fastapi`. Use `gt translate` for hosted translation. ## Work with me Read this entire prompt before acting. Respect the repository's instructions, package manager, architecture, design system, and existing changes. First inspect the repository for the framework, router, app directory, existing i18n library, GT configuration, source language, and build scripts. In a monorepo, identify the specific app or content directory; do not run setup at the workspace root. Do not ask me things you can determine from the code. If the intended project is unclear, ask one question: "What would you like to translate?" Offer concrete choices: this app or website, documentation or content files, a backend service, a connected content platform, or a small new demo. Include "Not sure, help me decide." Prefer your interactive question tool when available. If no repository is open, help me open one or choose a small demo before scaffolding anything. Ask for missing decisions one at a time: source language, target languages, and the first page or workflow to translate. Preserve existing locale choices; do not assume the source language is English or invent target markets. If I want help choosing, propose one target language for the first working example. Reuse an existing i18n setup where appropriate instead of automatically migrating the entire application. Explain the next meaningful step briefly, then do the work. Ask when a choice affects which organization/project you use, creates an unwanted duplicate, or changes the agreed scope. Once I have chosen the project, languages, and scope, proceed with the setup and translation needed for that outcome. ## Choose the right integration Read the matching quickstart before making framework changes: | Project | Integration | Quickstart | | --- | --- | --- | | Next.js App Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-quickstart.mdx | | Next.js Pages Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-pages-router-quickstart.mdx | | React SPA, including Vite | `gt-react` | https://generaltranslation.com/docs/react/react-spa-quickstart.mdx | | Server-rendered React | `gt-react` | https://generaltranslation.com/docs/react/react-quickstart.mdx | | TanStack Start | `gt-tanstack-start` | https://generaltranslation.com/docs/react/tanstack-start-quickstart.mdx | | React Native or Expo | `gt-react-native` | https://generaltranslation.com/docs/react/react-native-quickstart.mdx | | Vue | `gt-vue` | https://generaltranslation.com/docs/vue/quickstart.mdx | | Node.js backend | `gt-node` | https://generaltranslation.com/docs/node/quickstart.mdx | | Python backend | Follow the Python SDK guide | https://generaltranslation.com/docs/python/quickstart.mdx | | JSON, MDX, Markdown, YAML, or existing translation files | `gt` CLI | https://generaltranslation.com/docs/cli/quickstart.mdx | | Lower-level JavaScript translation | `generaltranslation` | https://generaltranslation.com/docs/platform/core/quickstart.mdx | For Mintlify, Sanity, Storyblok, or Google Drive, fetch https://generaltranslation.com/docs/integrations/llms.txt and follow that integration's quickstart. Do not apply a React setup wizard to a content integration. If I want GT to continuously maintain localization through GitHub, read https://generaltranslation.com/docs/platform/locadex/quickstart.mdx and walk me through connecting the repository and creating the appropriate automation. Do not enable auto-merge or change paid plans without my direction. ## Run the CLI without questions The CLI is interactive. When `init` or `configure` is missing an answer, it does not fail: it asks the question in the terminal and waits, with no timeout. In an agent session that wait never ends. So in this session: - Always pass `--no-interactive`. With it, a missing answer is a hard error that lists the flags still needed and changes no file. - Pass a flag for every question before you run the command. `--defaults` accepts the recommended local choices in one flag; you still need `--locales` and, outside local Vite and TanStack Start setups, `--dev-credentials` or `--no-dev-credentials`. Pass explicit `--default-locale`, `--locadex` or `--no-locadex`, `--react-setup` or `--no-react-setup`, and `--file-formats` values only when you want to override the defaults. Local Vite and TanStack Start setups default to `--no-live-translations`; pass `--live-translations` to opt in. Never combine the `--[no-]live-translations` and `--[no-]dev-credentials` flag families. - Pass `--json` to `init` and `configure`. It implies `--no-interactive`, writes one result event to stdout and the rendered screen to stderr. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` have no `--json` flag; `translate` prints a progress screen with terminal control sequences, so judge it by its exit code and by the files it writes: `public/_gt/.json`, `gt-lock.json` and `gt.config.json`. - If a command prints a question and stops, you are inside an interactive prompt. End the process and rerun it with `--no-interactive` and the missing flag. Never type an answer into it, and never run a command whose questions you have not answered with flags. - `gt login` is the one step that needs a person: it opens a browser and waits for the sign-in to finish. If no browser can open from this session, run it with `--no-browser`, give me the URL it prints, and wait for me to confirm. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` ask nothing when their flags are complete; a missing required flag is an error. ## Sign in with `gt login` Use account login for local CLI authentication. Do not begin by asking me to find and paste an API key. The examples below use `npx gt@latest` to avoid an old local CLI. Use the project's package manager or a current installed `gt` binary when appropriate. Inspect the version and available commands first: ```bash npm view gt version npx gt@latest --help npx gt@latest login --help ``` The CLI has no `--version` flag. `translate` prints "CLI Version: x.y.z" in its banner; `init --json` prints no banner. Read the published version with `npm view gt version` and the installed one from `node_modules/gt/package.json`. This workflow requires a CLI release with `login`, `whoami`, and `api-key create`. If the installed CLI lacks them, check the latest published release. If they are still unavailable, explain the release blocker and continue with local integration work that does not require credentials. Do not silently substitute the older `gt auth` flow, invent flags, or install an unpublished branch into my project. Check for an existing session with `npx gt@latest whoami`. If sign-in is needed, run: ```bash npx gt@latest login ``` Let me complete signup/sign-in and authorization in the browser. Keep the command running while approval is pending. In a remote or headless terminal, use: ```bash npx gt@latest login --no-browser ``` Show me the verification URL and code returned by that command; wait for successful authorization, then verify with `npx gt@latest whoami`. Do not ask for my password or extract OAuth tokens. Login authenticates the CLI; it does not by itself configure the app's project or create its runtime credentials. ## Select a project and create the credentials we need Reuse an existing configured project if it is the intended one. Check for conflicting project IDs in configuration and environment variables without printing secret values. Do not overwrite existing credentials or create another key unnecessarily. For a supported fresh app, run the setup wizard from the app directory after login, with every question answered by a flag. For a Next.js App Router app set up locally, with translations stored in the repository and an existing project reused: ```bash npx gt@latest init --no-interactive --json --defaults \ --default-locale --locales \ --no-locadex --react-setup --file-formats none \ --no-dev-credentials --project-id ``` This run asks nothing, installs gt-next, adds GTProvider to the root layout, adds withGTConfig to next.config.ts, creates loadTranslations.js and gt.config.json, and ends with `{"type":"result","command":"init","outcome":"success"}`. The wizard does not wrap any page text in ``, even though its completedSteps list says "wrapped JSX content". Internationalize every page yourself in step 4 of the implementation section. The wizard runs biome on the files it changes and may replace the project's indentation with tabs; restore the project's formatting. Ignore the warning "Unexpected export type in ./next.config.ts" when withGTConfig() was added correctly. Review the wizard's changes against the framework quickstart: automatic framework setup is experimental. `--defaults` covers local storage and the translations directory; pass `--storage` and `--translations-dir` only for other values. `--no-dev-credentials --project-id ` writes projectId to gt.config.json and creates no env file. Use it when no development key is wanted. If you already have a development key, add `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY` to `.env.development.local` yourself. `--dev-credentials --project-id ` saves a new development key and the project ID to `.env.local` instead; `--create-project --org-id --project-name ` creates the project first. `--no-react-setup` is for an app that already has the GT library; on an app without one it fails with "No GT runtime is installed, so select at least one file format to translate", which is right, since there would be nothing to translate. Pass `--locadex` only if we agreed to use hosted automation. Before a production build, move the development key (`NEXT_PUBLIC_GT_DEV_API_KEY` or `GT_DEV_API_KEY`) from `.env.local` to `.env.development.local`: `next dev` loads that file and `next build` does not, and a production build refuses to run with a development key present. A production build that ships local translation files needs no key. If the app already has framework setup, configure it directly from the docs. Use the authenticated CLI to discover resources: ```bash npx gt@latest api /v2/projects npx gt@latest api /v2/orgs ``` Follow pagination when present by passing `nextCursor` as `?cursor=`. `/v2/orgs` lists the organizations the signed-in user belongs to (an API key sees only its own). Creating a project also needs the `org:projects:create` permission in that organization; when `project create` is refused, ask me which organization to use or create the project in the Dashboard at https://dash.generaltranslation.com. Use actual returned IDs. Ask me to select when the destination is ambiguous. If my new account has no suitable organization, guide me through creating one at https://dash.generaltranslation.com, then retry discovery. When a new project is needed in the chosen organization: ```bash npx gt@latest project create \ --org-id \ --name \ --default-locale ``` Use the returned project ID. `project create` may require an organization key; read `npx gt@latest project create --help` first and fall back to creating the project in the Dashboard. For endpoint details or a missing higher-level command, inspect `npx gt@latest api --spec` and the current API docs before making a request. Local CLI operations can use the login session. Create separate project keys only where a runtime or unattended CI workflow needs one. Inspect `npx gt@latest api-key create --help` first. The command requires a key name and explicit permissions. A development runtime key needs `project:translations:generate`; a standard file translation workflow needs `project:files:read`, `project:files:write`, and `project:translations:enqueue`. Verify any additional operations against the API specification; do not grant every permission by default. `gt api-key create` prints the secret once to stdout. Capture that output directly into protected, ignored local configuration or the intended secret store without displaying it in tool output, chat, or logs. Use `--project-id` for the selected project, `--name` for its purpose, and `--permission` for the required permissions. Confirm success and the variable names without showing the key. Keep these credential roles distinct: - CLI/CI and server credentials use `GT_API_KEY` and `GT_PROJECT_ID`. Never put `GT_API_KEY` in browser code or a public-prefixed variable. - Development runtime translation uses `GT_DEV_API_KEY` and a project ID. Browser frameworks may need their documented public prefix, such as `VITE_GT_DEV_API_KEY`; for Next.js the wizard writes `NEXT_PUBLIC_GT_PROJECT_ID` and `NEXT_PUBLIC_GT_DEV_API_KEY`, and the CLI reads that project ID too, so `GT_PROJECT_ID` is only needed in CI. Only expose the narrowly scoped development key where the framework guide requires it; do not ship development credentials in production browser bundles. - OAuth credentials belong in the CLI's credential store. Do not copy them into the app or CI. Ensure local environment files are ignored by Git. Use placeholders in committed examples. Preserve unrelated environment settings. Logging in locally does not authenticate CI or a deployed server. ## Implement a complete first translation 1. Install the integration that matches the detected stack. For an existing project, make targeted changes and preserve its current behavior. 2. Create or update `gt.config.json` with the agreed source and target locales, source paths, and file mappings. Use the current configuration reference: https://generaltranslation.com/docs/cli/reference/config.mdx. Preserve existing settings. Configure translation output and loading together; for example, a Vite SPA's imported translation files must live within its source tree. Do not copy one framework's output path or provider setup into another framework. Add the translation output directory (for example `public/_gt/`) to `.gitignore` when translations are not committed. 3. Follow the framework's initialization and routing guide. Next.js App Router and Pages Router differ; React SPAs use `initializeGTSPA` before rendering; server runtimes need request-aware locale handling. Read the installed version's APIs before implementing them. 4. Internationalize the agreed page or workflow, including visible text, validation, placeholders, accessible labels, and metadata where relevant. In React, use `` for coherent static JSX. For standalone strings in gt-next, use `useGT()` in client components and in synchronous server components, and `getGT()` from `gt-next/server` in async server components and in `generateMetadata`. `useGT()` returns the function directly. For Next.js metadata, replace the static `metadata` export with `export async function generateMetadata()` that calls `getGT()` from `gt-next/server` and returns the translated title and description. Use `` or the framework's interpolation API for dynamic values; keep private values out of translation source. Use locale-aware number, date, currency, and plural handling. Follow the matching Vue, Node, or Python APIs for those stacks. 5. Add a language switcher to a suitable place in an app's existing UI. In gt-next, `` from `gt-next` renders directly inside a server component page; it carries its own client boundary. Give it an `aria-label` through `useGT()`. Preserve navigation and verify the selected locale survives navigation or reload as documented. For a backend or content-only project, verify locale selection and translated output through its actual API or content workflow instead. 6. Add useful context for ambiguous copy. Use the `context` prop on `` and the `$context` option in `gt()` and `getGT()` calls. `$context` on `` is a deprecated alias that the CLI flags when it scans the source. Preserve product names and terminology. Do not send secrets or runtime user data as translation source. For content files, preserve frontmatter, links, variables, and formatting according to the format guide. 7. Inspect the translation scope with `npx gt@latest translate --dry-run`, then run `npx gt@latest translate` for the agreed languages and scope. If this would unexpectedly translate a large corpus or exceed the agreed scope, clarify that before submitting it. `gt translate` also writes `gt-lock.json` and a `_versionId` into `gt.config.json`; commit both. Use the connected-platform workflow instead when the integration requires one. ## Verify and finish Ejecuta la comprobación de tipos (`npx tsc --noEmit`) y la compilación de producción (`next build`). Ejecuta el lint y las pruebas solo si el proyecto ya los tiene definidos. Inicia la aplicación y verifica la experiencia traducida real si dispones de herramientas de navegador: cambia entre las configuraciones regionales de origen y de destino, navega, recarga y comprueba la interpolación y el diseño. Una solicitud sin encabezado `Accept-Language` ni cookie renderiza la configuración regional predeterminada y registra una advertencia "gt-next: No locale could be determined" por cada búsqueda de traducción; es lo esperado al usar curl sin encabezado. Envía `Accept-Language: ` o `Cookie: generaltranslation.locale=` para comprobar una configuración regional de destino. Comprueba los textos largos y el diseño de derecha a izquierda si procede para el idioma seleccionado. En proyectos de backend y de contenido, inspecciona respuestas o archivos traducidos reales. No afirmes haberlo verificado en el navegador si no pudiste hacerlo. Corrige los fallos de configuración o de runtime antes de dar por completada la integración. Si te atascas, consulta la referencia correspondiente y revisa los errores de los comandos en lugar de volver a crear una y otra vez proyectos o claves. En aplicaciones que usan traducciones pregeneradas, prepara el flujo de trabajo de producción para que la traducción se ejecute antes de la compilación existente y sus archivos generados estén disponibles en el runtime. Conserva los pasos de compilación existentes, documenta los nombres de los secretos de CI y comprueba los requisitos de archivos locales o de CDN de la integración seleccionada. Si las traducciones se incluyen en el repositorio y no hay ninguna clave de CI, deja el script de compilación sin cambios. Ejecuta `npx gt@latest translate` localmente con la sesión iniciada cada vez que cambie el texto de origen y, después, haz commit de `public/_gt/.json`, `gt-lock.json` y `gt.config.json`. Añade `npx gt translate` al script de compilación solo si en CI hay configurada una `GT_API_KEY` con permisos de escritura de archivos y de cola de traducción. Usa `--publish` solo si el flujo de trabajo de CDN elegido lo requiere. No hagas despliegues en producción ni fusiones pull requests a menos que te lo haya pedido. Termina con un breve resumen de entrega: qué ha cambiado, qué proyecto y configuraciones regionales están configurados, cómo ejecutarlo, qué has verificado realmente y cualquier acción que me quede pendiente. Incluye la documentación pertinente y el enlace al Dashboard, pero ninguna credencial. El objetivo es tener una traducción funcional en mi proyecto y una forma clara de mantenerla actualizada. ```` ## 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` - **TanStack Start** → `gt-tanstack-start` - **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 Para una configuración nueva, ejecuta el comando desde el directorio de la aplicación con `--no-interactive` y un flag por cada pregunta. Sin `--no-interactive`, si falta una respuesta, se abre una pregunta en la terminal y el comando espera a que se responda; con él, si falta una respuesta, se produce un error que indica los flags que aún se necesitan, sin modificar ningún archivo: ```bash npx gt init --no-interactive --json --defaults --default-locale en --locales fr es --no-locadex --react-setup --file-formats none --no-dev-credentials ``` Para una configuración local de Vite o TanStack Start, sustituye `--no-dev-credentials` por `--no-live-translations`. No pases ambas familias de flags de credenciales. El asistente detecta el framework, crea o actualiza `gt.config.json` y puede seleccionar o crear un proyecto y aprovisionar una clave de runtime de desarrollo. Si se crea un proyecto o una clave sin una clave de herramientas ni un inicio de sesión guardado, primero se inicia sesión, algo que debe aprobar una persona. Las reescrituras del framework son experimentales y deben revisarse. Consulta los [flags y efectos secundarios de init](/docs/cli/reference/commands/init) antes de ejecutarlo. 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. Para una aplicación configurada manualmente, pide al desarrollador que ejecute `npx gt login` y luego vincula un proyecto existente con `projectId` en la configuración o `GT_PROJECT_ID` en el entorno. El inicio de sesión no selecciona ningún proyecto ni escribe archivos env; no vuelvas a ejecutar init solo para autenticarte. Para CI, haz commit de la configuración e inyecta una clave de herramientas con un alcance propio a través del almacén de secretos de CI: ```bash GT_API_KEY="your-api-key" # Otorga permisos para todo el flujo de trabajo de la CLI, no solo para la generación GT_PROJECT_ID="your-project-id" ``` El inicio de sesión de la CLI, las claves de runtime de desarrollo y las claves de herramientas de CI son independientes. Los SDK no leen las sesiones de la CLI; la clave de runtime de desarrollo que crea init no sustituye a `GT_API_KEY`. Nunca hagas commit de claves ni las incluyas en bundles desplegados para navegador o móvil. Lee [Credenciales de la CLI](/docs/cli/guides/configuring#credentials) antes de configurar la autenticación. Exige aprobación humana para el inicio de sesión y la creación de claves; `--no-browser` y el modo silencioso no hacen que el inicio de sesión sea desatendido. ## 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` | Configuración guiada; se ejecuta sin interacción con `--no-interactive` y flags. Puede modificar archivos del framework, dependencias, configuración y credenciales de runtime. | | `npx gt configure` | Configuración sin la reescritura de React; acepta los mismos flags salvo los de configuración del framework. Puede instalar dependencias y aprovisionar credenciales de runtime. Si solo necesitas cambiar la configuración, escríbela manualmente. | | `npx gt login` | Pide al desarrollador que apruebe el acceso a la cuenta para trabajar con la CLI. | | `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 escribir plantillas de origen para traducción manual sin llamar a la API. Disponible para los paquetes compatibles que se indican en la referencia de [`gt generate`](/docs/cli/reference/commands/generate). | | `npx gt translate --dry-run` | Para inspeccionar el alcance de la traducción sin llamar a la API ni escribir archivos de traducción. | | `npx gt api --list` | Para listar las operaciones de la API incluidas con la CLI instalada. | | `npx gt api --spec ` | Para inspeccionar una operación de la API incluida por ID de operación, ruta de la especificación o ruta concreta de la solicitud. Omite el endpoint para obtener la especificación completa. | | `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 ` | Con aprobación, crea un proyecto usando un usuario con sesión iniciada o una clave de organización autorizada para org:projects:create. | | `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. - Si tienes autorización para enviar contenido a la traducción alojada, 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 claves de API ni las expongas, no captures la salida estándar de la creación de claves en registros compartidos ni generes credenciales sin aprobación explícita. - 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. - Comandos de cuenta: [`gt login`](/docs/cli/reference/commands/login) y [`gt api-key create`](/docs/cli/reference/commands/api-key-create). - 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 puntos de entrada 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 punto de entrada 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. * [`agent-prompt.md`](/agent-prompt.md): el prompt inicial 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 y gestionar el Context. Utiliza streamable HTTP. Las herramientas de gestión de Context del servidor permiten listar, crear y actualizar Context Groups, sus términos del glosario e instrucciones personalizadas, importaciones y exportaciones, y asignaciones a Projects. Replican la [API de gestión de Context](/docs/platform/openapi/reference/context-management/list-groups). 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 API Key aceptan claves de Project (`gtx-api-`) y Organization keys (`gtx-org-`). Las claves `gtx-dev-` existentes siguen autenticándose como claves de Project. Cada herramienta comprueba los permisos de la clave para la acción solicitada. Configura [permisos de clave personalizados](/docs/platform/dashboard/reference/api-keys) para las herramientas que necesite tu agente. Usa `list_orgs` para encontrar un ID de Organization y `list_projects` para encontrar un ID del Project. Ninguna de estas herramientas de descubrimiento requiere permisos sobre recursos. Pasa los ID obtenidos como `orgId` y `projectId` a otras herramientas. Las claves de Project y las Organization keys solo descubren los recursos a los que están vinculadas, y una clave de Project puede omitir `projectId` para usar su propio Project. Las herramientas de gestión de Context requieren `org:context:read` u `org:context:write`. Concede a una Organization key el permiso de **Context** correspondiente, o autoriza ese mismo acceso a Context de la Organization durante el inicio de sesión OAuth de MCP. Las claves de Project no pueden usar estas herramientas. Pasa un `orgId` a `list_context_groups` y `create_context_group`, y un `groupId` a las herramientas que operan sobre un grupo existente. El cuerpo de las solicitudes MCP está limitado a 100 MiB. Algunas herramientas pueden imponer límites más estrictos a sus entradas. 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 y preparar `gt.config.json`. Obtén aprobación antes de ejecutar [`npx gt init`](/docs/cli/reference/commands/init) con `--dev-credentials` o `--create-project`, ya que crean claves o Projects. * **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:** generar o exponer credenciales sin aprobación, 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.