` traducido y las metaetiquetas. Lo que Start deja en tus manos: los catálogos de mensajes y el runtime que los consulta, la detección de la configuración regional y la cookie que recuerda la elección del usuario, el atributo `<html lang>` en tu shell raíz, el formato de plurales y de números, los enlaces `hreflang` y, por supuesto, las propias traducciones. La guía de i18n de TanStack documenta Paraglide JS en profundidad, incluida una configuración inicial de SSR con TanStack Start, y enlaza a guías de la comunidad para Intlayer y use-intl. La CLI de TanStack también incluye un complemento `paraglide` para aplicaciones nuevas. ## Tus opciones | Biblioteca | Cómo escribes el texto | Configuración regional en el servidor | De dónde provienen las traducciones | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Paraglide JS](https://paraglidejs.com/tanstack-start) | Mensajes en archivos JSON por configuración regional, compilados a funciones tipadas como `m.greeting()` | `paraglideMiddleware` envuelve el manejador de solicitud del servidor; las estrategias incluyen URL, cookie e idioma preferido | Tú, traductores o un comando de traducción automática que ejecutas sobre los archivos | | [react-i18next](https://react.i18next.com/latest/ssr) | Claves en espacios de nombres JSON, renderizadas con `t('home.title')` | Su documentación no incluye integración con TanStack Start; tú proporcionas una instancia per-request y pasas `initialLanguage` e `initialI18nStore` al cliente | Tú, traductores o un sistema de gestión de traducciones (TMS) como Locize | | [Lingui](https://lingui.dev/ref/vite-plugin) | Macros `<Trans>` inline, extraídas a catálogos PO | Su plugin de Vite compila los catálogos; tú activas la configuración regional de la solicitud en el servidor y en el navegador | Tú, traductores o un servicio sincronizado con los catálogos | | General Translation (`gt-tanstack-start`, experimental) | JSX envuelto en [`<T>`](/docs/react/reference/components/t), cadenas con [`useGT`](/docs/react/reference/hooks/use-gt) | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware): prefijo de URL (activación voluntaria), luego cookie, luego `Accept-Language` y, por último, la configuración regional predeterminada | Generadas por [`npx gt translate`](/docs/cli/reference/commands/translate) y revisadas en el panel de control | Usa Paraglide JS si quieres la configuración inicial que documenta TanStack, funciones de mensajes tipadas y tree-shaking por mensaje, y ya cuentas con una forma de rellenar los archivos JSON. Usa react-i18next si vas a reutilizar catálogos de i18next de otra aplicación. Usa Lingui si tus traductores trabajan con archivos PO. Usa General Translation si quieres que el texto se mantenga inline en tus componentes y que las traducciones se generen a partir de él y se mantengan siempre actualizadas. (Consulta [General Translation vs. Paraglide JS](/kb/general-translation-vs-paraglide) para ver una comparación más detallada). `gt-tanstack-start` es experimental: según la documentación de General Translation, puede introducir cambios incompatibles y todavía no se recomienda para producción. Si hoy necesitas una configuración inicial estable para React, consulta [¿Cómo traduzco una aplicación de React?](/kb/translate-react-app). ## Añadir General Translation a TanStack Start En esta guía añadirás español y francés a una página, traducirás una función de servidor y, después, moverás cada idioma a su propia URL. Se ha probado con una aplicación generada con `npx @tanstack/cli@latest create` (`@tanstack/react-start` 1.169.4), `gt-tanstack-start@11.4.16` y `gt@2.26.11`. El paquete requiere `@tanstack/react-start` 1.159.0 o posterior y solo admite ESM. El [asistente de configuración inicial](/docs/cli/reference/commands/init), `npx gt@2.26.11 init`, aplica los mismos cambios que los pasos 1 a 4: instala el paquete, escribe el cargador, el middleware, la llamada al router y la ruta raíz, e indica todo lo que no puede modificar de forma segura. Revisa el diff que genera o sigue los pasos manualmente. ### 1. Instala la biblioteca y la CLI ```bash npm install gt-tanstack-start@11.4.16 npm install --save-dev gt@2.26.11 ``` `gt-tanstack-start` exporta los componentes de React compartidos, como [`<T>`](/docs/react/reference/components/t) y [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), además de funciones auxiliares para el servidor. La CLI de `gt` detecta tu contenido de origen y genera los archivos de traducción. ### 2. Configura tus idiomas ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` Mantén la salida dentro de `src/` para que Vite pueda importar los archivos. Después, añade un cargador: ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`./_gt/${locale}.json`); return translations.default; } ``` ### 3. Registra el middleware de solicitudes ```ts title="src/start.ts" import { createCsrfMiddleware, createStart } from '@tanstack/react-start'; import { gtMiddleware } from 'gt-tanstack-start'; // Conserva la protección CSRF de TanStack Start para las funciones de servidor. const csrfMiddleware = createCsrfMiddleware({ filter: ({ handlerType }) => handlerType === 'serverFn', }); export const startInstance = createStart(() => ({ requestMiddleware: [csrfMiddleware, gtMiddleware], })); ``` El [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) de General Translation resuelve la configuración regional una vez por solicitud: primero consulta la cookie de configuración regional, después `Accept-Language` y, por último, `defaultLocale`, y guarda el resultado en la cookie. Cada solicitud mantiene su propia configuración regional, aunque se rendericen varias a la vez. ### 4. Inicializa la biblioteca e hidrata la ruta raíz Agrega el inicializador en el ámbito del módulo de tu archivo `src/router.tsx` existente: ```tsx title="src/router.tsx" import { initializeGT } from 'gt-tanstack-start'; import gtConfig from '../gt.config.json'; import loadTranslations from './loadTranslations'; initializeGT({ ...gtConfig, loadTranslations }); // ... tu getRouter() existente ``` Luego, carga la configuración regional y sus traducciones en la ruta raíz y pásalas a [`<GTProvider>`](/docs/react/reference/components/gt-provider): ```tsx title="src/routes/__root.tsx" import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'; import { GTProvider, LocaleSelector, getLocale, getTranslationsSnapshot, } from 'gt-tanstack-start'; export const Route = createRootRoute({ // Se ejecuta en el servidor en la primera solicitud, por lo que el HTML ya está traducido. loader: async () => { const locale = getLocale(); return { locale, translations: await getTranslationsSnapshot(locale) }; }, shellComponent: RootDocument, }); function RootDocument({ children }: { children: React.ReactNode }) { const { locale, translations } = Route.useLoaderData(); return ( <html lang={locale}> <head> <HeadContent /> </head> <body> <GTProvider locale={locale} translations={translations}> <LocaleSelector /> {children} </GTProvider> <Scripts /> </body> </html> ); } ``` [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) lee la configuración regional de la solicitud en el servidor y la cookie en el navegador, de modo que ambos renderizados coinciden. Al establecer `lang={locale}`, se sustituye el `lang="en"` codificado de forma fija en el shell de la plantilla inicial. ### 5. Marca el contenido para traducir ```tsx title="src/routes/index.tsx" import { createFileRoute } from '@tanstack/react-router'; import { T, useGT } from 'gt-tanstack-start'; export const Route = createFileRoute('/')({ component: Home }); function Home() { const gt = useGT(); return ( <main> <T> <h1>Find your next project</h1> <p>Explore projects from teams around the world.</p> </T> <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} /> </main> ); } ``` [`<T>`](/docs/react/reference/components/t) traduce el encabezado y el párrafo como una sola unidad y usa el marcado como contexto. [`useGT`](/docs/react/reference/hooks/use-gt) se encarga de las cadenas de los atributos. Para nombres, cantidades y fechas dentro de [`<T>`](/docs/react/reference/components/t), usa los [componentes de variables y de formato](/docs/react/guides/formatting-variables). ### 6. Generar traducciones Inicia sesión con [`npx gt login`](/docs/cli/reference/commands/login), define `GT_PROJECT_ID` (o `projectId` en `gt.config.json`) y ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate). Este comando genera `src/_gt/es.json` y `src/_gt/fr.json`. La generación se factura según un [modelo de precios basado en el uso](https://generaltranslation.com/pricing). Para probar la configuración inicial sin una cuenta, ejecuta [`npx gt generate`](/docs/cli/reference/commands/generate). Este comando genera los mismos archivos con el texto de origen en inglés, que luego editas a mano. Si una configuración regional aún no tiene archivo, se renderiza el texto de origen y se registra una advertencia indicando que no se pudieron cargar sus traducciones. ### 7. Ejecútalo y cambia de idioma Ejecuta `npm run dev` y elige Español en el selector. La elección se guarda en la cookie de configuración regional, la página se recarga y el servidor renderiza el contenido en español. En la aplicación de prueba, una compilación de producción devolvió `<html lang="es">` con el encabezado y el marcador de posición en español ante una solicitud con `Accept-Language: es`, y `<html lang="en">` con el contenido en inglés ante una solicitud sin preferencia de idioma. ## Traducir en funciones de servidor y metadatos [`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) traduce cadenas dentro de una función de servidor con la configuración regional de la solicitud: ```tsx title="src/routes/account.tsx" import { createFileRoute } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/react-start'; import { getGT } from 'gt-tanstack-start'; const loadAccount = createServerFn({ method: 'GET' }).handler(async () => { const gt = await getGT(); return { title: gt('Your account') }; }); export const Route = createFileRoute('/account')({ loader: () => loadAccount(), // El título traducido también se usa como <title> de la página. head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }), component: () => <h1>{Route.useLoaderData().title}</h1>, }); ``` Estas funciones auxiliares lanzan un error en el servidor si se ejecutan fuera de una solicitud gestionada por [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), por ejemplo, en el ámbito del módulo. En [Uso de funciones de servidor](/docs/react/tanstack-start/using-server-functions) también se tratan las entradas del diccionario y los mensajes registrados. ## Asigna a cada idioma su propia URL La configuración inicial anterior sirve todos los idiomas en la misma URL, que se elige según la cookie o el idioma del navegador. Los motores de búsqueda indexan un solo idioma por URL, así que [las páginas públicas necesitan un prefijo](/kb/locale-routing-seo), como `/es/about`. Mueve las rutas a un segmento opcional, como `src/routes/{-$locale}/index.tsx` con `createFileRoute('/{-$locale}/')`, y después activa el enrutamiento por configuración regional: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "localeRouting": true } ``` Así, el middleware comprueba primero la ruta y el selector navega a la URL con prefijo. En la aplicación de prueba, `/es` y `/es/account` se renderizaron en español con `<html lang="es">`, y `/` se renderizó en inglés. Una URL sin prefijo sigue respetando la cookie en el caso de un visitante recurrente, y los [enlaces `hreflang`](/kb/what-is-hreflang) tienes que añadirlos tú mismo en el `head` de cada ruta. (Consulta la [configuración inicial del enrutamiento por configuración regional](/docs/react/tanstack-start/setup#locale-routing)). ## Publica y mantén las traducciones al día Traduce antes de cada compilación para que los textos nuevos se publiquen en todos los idiomas: ```json title="package.json" { "scripts": { "build": "gt validate && gt translate && vite build" } } ``` [`gt validate`](/docs/cli/reference/commands/validate) hace fallar la compilación si hay contenido que rompería la traducción, antes de realizar cualquier llamada a la API. En CI, configura `GT_PROJECT_ID` y una Clave de API del proyecto como `GT_API_KEY` con los permisos **Archivos > Escritura** y **Cola de traducción > Habilitada** ([credenciales de la CLI](/docs/cli/guides/configuring#credentials)). Las ejecuciones posteriores solo traducen el contenido de origen nuevo o modificado. Los revisores pueden editar cualquier cadena en el [Editor de Traducciones](/docs/platform/dashboard/guides/reviewing-translations) de General Translation, y [`npx gt save-local`](/docs/cli/reference/commands/save-local) sincroniza las ediciones hechas en los archivos JSON para que las ejecuciones posteriores las conserven. Un [grupo de contexto](/docs/platform/dashboard/guides/defining-context-for-translations) reúne tu glosario y tus prompts personalizados, para que los nombres de producto y el tono sean coherentes en esta aplicación, tu documentación y tus demás proyectos. [Locadex](/docs/platform/locadex/guides/configuring-automations), el Agente de IA de General Translation, es compatible con aplicaciones de TanStack Start y puede traducir textos nuevos mediante pull requests. ## Preguntas frecuentes ### ¿TanStack Start incluye i18n de forma nativa? No. TanStack Router te ofrece segmentos opcionales de configuración regional y reescrituras de URL, y Start te proporciona middleware y cargadores, pero los mensajes, la detección de la configuración regional y las traducciones dependen de una biblioteca. ### ¿Puedo usar react-i18next con TanStack Start? Sí, como biblioteca de React. TanStack no lo documenta, y la guía de SSR de react-i18next solo menciona integraciones para Next.js, Remix y Gatsby, así que tendrás que configurar tú mismo la instancia per-request y la hidratación en el cliente. ### ¿Está gt-tanstack-start listo para producción? Todavía no: General Translation lo considera experimental. Fija la versión y revisa el registro de cambios antes de actualizar. ## Conclusiones clave * TanStack Start no incluye una capa de i18n; sus segmentos opcionales `/{-$locale}`, el middleware de `createStart` y los cargadores raíz son los puntos donde puedes integrarla. * Resuelve la configuración regional en cada solicitud en el servidor, hidrata el cliente con los mismos mensajes y establece `<html lang>` desde el cargador en lugar de usar el `lang="en"` fijo de la plantilla inicial. * Paraglide JS es la biblioteca que documenta TanStack; tanto esta como react-i18next y Lingui renderizan las traducciones que tú proporcionas. * El paquete experimental `gt-tanstack-start` de General Translation añade [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), [`initializeGT`](/docs/react/reference/config#initialize) y [`<GTProvider>`](/docs/react/reference/components/gt-provider), mantiene el texto inline en [`<T>`](/docs/react/reference/components/t), y [`npx gt translate`](/docs/cli/reference/commands/translate) genera `src/_gt/[locale].json`. * Añade `"localeRouting": true` con un segmento opcional `{-$locale}` cuando cada idioma necesite su propia URL indexable. ## 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. - [General Translation vs. Paraglide JS: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-paraglide.mdx): Elige General Translation para mantener el texto inline y generar traducciones que respetan la estructura de tus componentes de React, con terminología compartida y revisión en el panel de control. Elige Paraglide JS si buscas funciones de mensaje compiladas y tipadas, con tree-shaking por mensaje. Paraglide renderiza tus catálogos; General Translation conecta el texto de origen con la generación de traducciones y sus actualizaciones continuas. - [¿Cuál es la mejor biblioteca de i18n para una aplicación React?](https://generaltranslation.com/es/kb/best-react-i18n-library.mdx): Las cuatro principales bibliotecas de i18n para React son gt-react de General Translation, react-i18next, Lingui y React Intl. Las cuatro renderizan traducciones y les dan formato, pero solo gt-react también las genera a partir de textos escritos inline en tu JSX. Elige react-i18next si quieres conservar los catálogos y plugins de i18next, Lingui si buscas extracción a catálogos compilados y React Intl si prefieres FormatJS y el formato de mensajes ICU. - [Redirecciones de idioma y SEO: ¿URL, cookie o Accept-Language?](https://generaltranslation.com/es/kb/locale-routing-seo.mdx): Deja que la URL determine el idioma de cada página que quieras indexar, porque Googlebot no envía la cabecera Accept-Language y rastrea sobre todo desde direcciones de EE. UU. Recurre a la preferencia guardada en una cookie y, en su defecto, a Accept-Language solo para decidir adónde redirige una raíz neutral como /, mediante una redirección temporal 302 o 307. - [¿Cómo traduzco una aplicación de React?](https://generaltranslation.com/es/kb/translate-react-app.mdx): Traducir una aplicación de React significa internacionalizar sus componentes para que se rendericen en el idioma del usuario y, después, traducir cada cadena a todos los idiomas que admitas. gt-react de General Translation traduce JSX en el mismo documento con el componente `<T>`, y npx gt translate genera un archivo por idioma. ## Previous and next questions - Previous question: [¿Qué hace el agente Locadex?](https://generaltranslation.com/es/kb/what-is-locadex.mdx) - Next question: [¿Cómo agrego i18n a una aplicación de Next.js con Pages Router?](https://generaltranslation.com/es/kb/add-i18n-to-nextjs-pages-router.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.

# General Translation Knowledge Base: ¿Cómo agrego i18n a TanStack Start? URL: https://generaltranslation.com/es/kb/add-i18n-to-tanstack-start.mdx Docs index: https://generaltranslation.com/llms.txt Description: TanStack Start no incluye i18n de forma nativa, así que debes agregar una biblioteca que resuelva la configuración regional en cada solicitud del servidor, normalmente a partir de un prefijo de URL o de una cookie, y que cargue los mensajes antes de renderizar. Paraglide JS, react-i18next y Lingui renderizan las traducciones que tú proporcionas; el paquete experimental gt-tanstack-start de General Translation, además, las genera a partir del texto escrito inline en JSX. Category: Internacionalización Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 TanStack Start no incluye una capa de i18n, así que tienes que añadir tú mismo tres elementos: una biblioteca que renderice el texto en el idioma activo, un mecanismo para resolver ese idioma en cada solicitud del servidor y las propias traducciones. Start renderiza el documento completo en el servidor y luego lo hidrata en el navegador, por lo que el servidor y el cliente necesitan la misma configuración regional y los mismos mensajes; de lo contrario, el primer pintado se muestra en el idioma equivocado o la hidratación falla. ## Lo que TanStack Start te ofrece y lo que deja en tus manos TanStack Start es «un framework de React full-stack impulsado por TanStack Router», con renderizado server-side (SSR) de documento completo, streaming, funciones de servidor y middleware de solicitudes ([descripción general de TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview)). Varias de esas piezas son la base de cualquier configuración inicial de i18n: * **URL con configuración regional.** Un parámetro de ruta opcional como `/{-$locale}/about` coincide con `/about`, `/es/about` y `/fr/about` con un solo archivo de ruta; como alternativa, la opción `rewrite` del router puede añadir y quitar un prefijo de configuración regional ([guía de i18n de TanStack Router](https://tanstack.com/router/latest/docs/guide/internationalization-i18n)). * **Middleware de solicitudes.** El middleware registrado con `createStart` en `src/start.ts` se ejecuta antes de cada solicitud, incluidas las de SSR y las funciones de servidor ([middleware de TanStack Start](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)). Ahí es donde una biblioteca de i18n lee la URL, una cookie o la cabecera `Accept-Language`. * **Cargadores y `head`.** Un cargador de la ruta raíz puede cargar los mensajes de la configuración regional antes del renderizado, y el `head` de cada ruta define el `` traducido y las metaetiquetas. Lo que Start deja en tus manos: los catálogos de mensajes y el runtime que los consulta, la detección de la configuración regional y la cookie que recuerda la elección del usuario, el atributo `<html lang>` en tu shell raíz, el formato de plurales y de números, los enlaces `hreflang` y, por supuesto, las propias traducciones. La guía de i18n de TanStack documenta Paraglide JS en profundidad, incluida una configuración inicial de SSR con TanStack Start, y enlaza a guías de la comunidad para Intlayer y use-intl. La CLI de TanStack también incluye un complemento `paraglide` para aplicaciones nuevas. ## Tus opciones | Biblioteca | Cómo escribes el texto | Configuración regional en el servidor | De dónde provienen las traducciones | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Paraglide JS](https://paraglidejs.com/tanstack-start) | Mensajes en archivos JSON por configuración regional, compilados a funciones tipadas como `m.greeting()` | `paraglideMiddleware` envuelve el manejador de solicitud del servidor; las estrategias incluyen URL, cookie e idioma preferido | Tú, traductores o un comando de traducción automática que ejecutas sobre los archivos | | [react-i18next](https://react.i18next.com/latest/ssr) | Claves en espacios de nombres JSON, renderizadas con `t('home.title')` | Su documentación no incluye integración con TanStack Start; tú proporcionas una instancia per-request y pasas `initialLanguage` e `initialI18nStore` al cliente | Tú, traductores o un sistema de gestión de traducciones (TMS) como Locize | | [Lingui](https://lingui.dev/ref/vite-plugin) | Macros `<Trans>` inline, extraídas a catálogos PO | Su plugin de Vite compila los catálogos; tú activas la configuración regional de la solicitud en el servidor y en el navegador | Tú, traductores o un servicio sincronizado con los catálogos | | General Translation (`gt-tanstack-start`, experimental) | JSX envuelto en [`<T>`](/docs/react/reference/components/t), cadenas con [`useGT`](/docs/react/reference/hooks/use-gt) | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware): prefijo de URL (activación voluntaria), luego cookie, luego `Accept-Language` y, por último, la configuración regional predeterminada | Generadas por [`npx gt translate`](/docs/cli/reference/commands/translate) y revisadas en el panel de control | Usa Paraglide JS si quieres la configuración inicial que documenta TanStack, funciones de mensajes tipadas y tree-shaking por mensaje, y ya cuentas con una forma de rellenar los archivos JSON. Usa react-i18next si vas a reutilizar catálogos de i18next de otra aplicación. Usa Lingui si tus traductores trabajan con archivos PO. Usa General Translation si quieres que el texto se mantenga inline en tus componentes y que las traducciones se generen a partir de él y se mantengan siempre actualizadas. (Consulta [General Translation vs. Paraglide JS](/kb/general-translation-vs-paraglide) para ver una comparación más detallada). `gt-tanstack-start` es experimental: según la documentación de General Translation, puede introducir cambios incompatibles y todavía no se recomienda para producción. Si hoy necesitas una configuración inicial estable para React, consulta [¿Cómo traduzco una aplicación de React?](/kb/translate-react-app). ## Añadir General Translation a TanStack Start En esta guía añadirás español y francés a una página, traducirás una función de servidor y, después, moverás cada idioma a su propia URL. Se ha probado con una aplicación generada con `npx @tanstack/cli@latest create` (`@tanstack/react-start` 1.169.4), `gt-tanstack-start@11.4.16` y `gt@2.26.11`. El paquete requiere `@tanstack/react-start` 1.159.0 o posterior y solo admite ESM. El [asistente de configuración inicial](/docs/cli/reference/commands/init), `npx gt@2.26.11 init`, aplica los mismos cambios que los pasos 1 a 4: instala el paquete, escribe el cargador, el middleware, la llamada al router y la ruta raíz, e indica todo lo que no puede modificar de forma segura. Revisa el diff que genera o sigue los pasos manualmente. ### 1. Instala la biblioteca y la CLI ```bash npm install gt-tanstack-start@11.4.16 npm install --save-dev gt@2.26.11 ``` `gt-tanstack-start` exporta los componentes de React compartidos, como [`<T>`](/docs/react/reference/components/t) y [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), además de funciones auxiliares para el servidor. La CLI de `gt` detecta tu contenido de origen y genera los archivos de traducción. ### 2. Configura tus idiomas ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` Mantén la salida dentro de `src/` para que Vite pueda importar los archivos. Después, añade un cargador: ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`./_gt/${locale}.json`); return translations.default; } ``` ### 3. Registra el middleware de solicitudes ```ts title="src/start.ts" import { createCsrfMiddleware, createStart } from '@tanstack/react-start'; import { gtMiddleware } from 'gt-tanstack-start'; // Conserva la protección CSRF de TanStack Start para las funciones de servidor. const csrfMiddleware = createCsrfMiddleware({ filter: ({ handlerType }) => handlerType === 'serverFn', }); export const startInstance = createStart(() => ({ requestMiddleware: [csrfMiddleware, gtMiddleware], })); ``` El [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) de General Translation resuelve la configuración regional una vez por solicitud: primero consulta la cookie de configuración regional, después `Accept-Language` y, por último, `defaultLocale`, y guarda el resultado en la cookie. Cada solicitud mantiene su propia configuración regional, aunque se rendericen varias a la vez. ### 4. Inicializa la biblioteca e hidrata la ruta raíz Agrega el inicializador en el ámbito del módulo de tu archivo `src/router.tsx` existente: ```tsx title="src/router.tsx" import { initializeGT } from 'gt-tanstack-start'; import gtConfig from '../gt.config.json'; import loadTranslations from './loadTranslations'; initializeGT({ ...gtConfig, loadTranslations }); // ... tu getRouter() existente ``` Luego, carga la configuración regional y sus traducciones en la ruta raíz y pásalas a [`<GTProvider>`](/docs/react/reference/components/gt-provider): ```tsx title="src/routes/__root.tsx" import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'; import { GTProvider, LocaleSelector, getLocale, getTranslationsSnapshot, } from 'gt-tanstack-start'; export const Route = createRootRoute({ // Se ejecuta en el servidor en la primera solicitud, por lo que el HTML ya está traducido. loader: async () => { const locale = getLocale(); return { locale, translations: await getTranslationsSnapshot(locale) }; }, shellComponent: RootDocument, }); function RootDocument({ children }: { children: React.ReactNode }) { const { locale, translations } = Route.useLoaderData(); return ( <html lang={locale}> <head> <HeadContent /> </head> <body> <GTProvider locale={locale} translations={translations}> <LocaleSelector /> {children} </GTProvider> <Scripts /> </body> </html> ); } ``` [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) lee la configuración regional de la solicitud en el servidor y la cookie en el navegador, de modo que ambos renderizados coinciden. Al establecer `lang={locale}`, se sustituye el `lang="en"` codificado de forma fija en el shell de la plantilla inicial. ### 5. Marca el contenido para traducir ```tsx title="src/routes/index.tsx" import { createFileRoute } from '@tanstack/react-router'; import { T, useGT } from 'gt-tanstack-start'; export const Route = createFileRoute('/')({ component: Home }); function Home() { const gt = useGT(); return ( <main> <T> <h1>Find your next project</h1> <p>Explore projects from teams around the world.</p> </T> <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} /> </main> ); } ``` [`<T>`](/docs/react/reference/components/t) traduce el encabezado y el párrafo como una sola unidad y usa el marcado como contexto. [`useGT`](/docs/react/reference/hooks/use-gt) se encarga de las cadenas de los atributos. Para nombres, cantidades y fechas dentro de [`<T>`](/docs/react/reference/components/t), usa los [componentes de variables y de formato](/docs/react/guides/formatting-variables). ### 6. Generar traducciones Inicia sesión con [`npx gt login`](/docs/cli/reference/commands/login), define `GT_PROJECT_ID` (o `projectId` en `gt.config.json`) y ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate). Este comando genera `src/_gt/es.json` y `src/_gt/fr.json`. La generación se factura según un [modelo de precios basado en el uso](https://generaltranslation.com/pricing). Para probar la configuración inicial sin una cuenta, ejecuta [`npx gt generate`](/docs/cli/reference/commands/generate). Este comando genera los mismos archivos con el texto de origen en inglés, que luego editas a mano. Si una configuración regional aún no tiene archivo, se renderiza el texto de origen y se registra una advertencia indicando que no se pudieron cargar sus traducciones. ### 7. Ejecútalo y cambia de idioma Ejecuta `npm run dev` y elige Español en el selector. La elección se guarda en la cookie de configuración regional, la página se recarga y el servidor renderiza el contenido en español. En la aplicación de prueba, una compilación de producción devolvió `<html lang="es">` con el encabezado y el marcador de posición en español ante una solicitud con `Accept-Language: es`, y `<html lang="en">` con el contenido en inglés ante una solicitud sin preferencia de idioma. ## Traducir en funciones de servidor y metadatos [`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) traduce cadenas dentro de una función de servidor con la configuración regional de la solicitud: ```tsx title="src/routes/account.tsx" import { createFileRoute } from '@tanstack/react-router'; import { createServerFn } from '@tanstack/react-start'; import { getGT } from 'gt-tanstack-start'; const loadAccount = createServerFn({ method: 'GET' }).handler(async () => { const gt = await getGT(); return { title: gt('Your account') }; }); export const Route = createFileRoute('/account')({ loader: () => loadAccount(), // El título traducido también se usa como <title> de la página. head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }), component: () => <h1>{Route.useLoaderData().title}</h1>, }); ``` Estas funciones auxiliares lanzan un error en el servidor si se ejecutan fuera de una solicitud gestionada por [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), por ejemplo, en el ámbito del módulo. En [Uso de funciones de servidor](/docs/react/tanstack-start/using-server-functions) también se tratan las entradas del diccionario y los mensajes registrados. ## Asigna a cada idioma su propia URL La configuración inicial anterior sirve todos los idiomas en la misma URL, que se elige según la cookie o el idioma del navegador. Los motores de búsqueda indexan un solo idioma por URL, así que [las páginas públicas necesitan un prefijo](/kb/locale-routing-seo), como `/es/about`. Mueve las rutas a un segmento opcional, como `src/routes/{-$locale}/index.tsx` con `createFileRoute('/{-$locale}/')`, y después activa el enrutamiento por configuración regional: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "localeRouting": true } ``` Así, el middleware comprueba primero la ruta y el selector navega a la URL con prefijo. En la aplicación de prueba, `/es` y `/es/account` se renderizaron en español con `<html lang="es">`, y `/` se renderizó en inglés. Una URL sin prefijo sigue respetando la cookie en el caso de un visitante recurrente, y los [enlaces `hreflang`](/kb/what-is-hreflang) tienes que añadirlos tú mismo en el `head` de cada ruta. (Consulta la [configuración inicial del enrutamiento por configuración regional](/docs/react/tanstack-start/setup#locale-routing)). ## Publica y mantén las traducciones al día Traduce antes de cada compilación para que los textos nuevos se publiquen en todos los idiomas: ```json title="package.json" { "scripts": { "build": "gt validate && gt translate && vite build" } } ``` [`gt validate`](/docs/cli/reference/commands/validate) hace fallar la compilación si hay contenido que rompería la traducción, antes de realizar cualquier llamada a la API. En CI, configura `GT_PROJECT_ID` y una Clave de API del proyecto como `GT_API_KEY` con los permisos **Archivos > Escritura** y **Cola de traducción > Habilitada** ([credenciales de la CLI](/docs/cli/guides/configuring#credentials)). Las ejecuciones posteriores solo traducen el contenido de origen nuevo o modificado. Los revisores pueden editar cualquier cadena en el [Editor de Traducciones](/docs/platform/dashboard/guides/reviewing-translations) de General Translation, y [`npx gt save-local`](/docs/cli/reference/commands/save-local) sincroniza las ediciones hechas en los archivos JSON para que las ejecuciones posteriores las conserven. Un [grupo de contexto](/docs/platform/dashboard/guides/defining-context-for-translations) reúne tu glosario y tus prompts personalizados, para que los nombres de producto y el tono sean coherentes en esta aplicación, tu documentación y tus demás proyectos. [Locadex](/docs/platform/locadex/guides/configuring-automations), el Agente de IA de General Translation, es compatible con aplicaciones de TanStack Start y puede traducir textos nuevos mediante pull requests. ## Preguntas frecuentes ### ¿TanStack Start incluye i18n de forma nativa? No. TanStack Router te ofrece segmentos opcionales de configuración regional y reescrituras de URL, y Start te proporciona middleware y cargadores, pero los mensajes, la detección de la configuración regional y las traducciones dependen de una biblioteca. ### ¿Puedo usar react-i18next con TanStack Start? Sí, como biblioteca de React. TanStack no lo documenta, y la guía de SSR de react-i18next solo menciona integraciones para Next.js, Remix y Gatsby, así que tendrás que configurar tú mismo la instancia per-request y la hidratación en el cliente. ### ¿Está gt-tanstack-start listo para producción? Todavía no: General Translation lo considera experimental. Fija la versión y revisa el registro de cambios antes de actualizar. ## Conclusiones clave * TanStack Start no incluye una capa de i18n; sus segmentos opcionales `/{-$locale}`, el middleware de `createStart` y los cargadores raíz son los puntos donde puedes integrarla. * Resuelve la configuración regional en cada solicitud en el servidor, hidrata el cliente con los mismos mensajes y establece `<html lang>` desde el cargador en lugar de usar el `lang="en"` fijo de la plantilla inicial. * Paraglide JS es la biblioteca que documenta TanStack; tanto esta como react-i18next y Lingui renderizan las traducciones que tú proporcionas. * El paquete experimental `gt-tanstack-start` de General Translation añade [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), [`initializeGT`](/docs/react/reference/config#initialize) y [`<GTProvider>`](/docs/react/reference/components/gt-provider), mantiene el texto inline en [`<T>`](/docs/react/reference/components/t), y [`npx gt translate`](/docs/cli/reference/commands/translate) genera `src/_gt/[locale].json`. * Añade `"localeRouting": true` con un segmento opcional `{-$locale}` cuando cada idioma necesite su propia URL indexable. ## 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. - [General Translation vs. Paraglide JS: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-paraglide.mdx): Elige General Translation para mantener el texto inline y generar traducciones que respetan la estructura de tus componentes de React, con terminología compartida y revisión en el panel de control. Elige Paraglide JS si buscas funciones de mensaje compiladas y tipadas, con tree-shaking por mensaje. Paraglide renderiza tus catálogos; General Translation conecta el texto de origen con la generación de traducciones y sus actualizaciones continuas. - [¿Cuál es la mejor biblioteca de i18n para una aplicación React?](https://generaltranslation.com/es/kb/best-react-i18n-library.mdx): Las cuatro principales bibliotecas de i18n para React son gt-react de General Translation, react-i18next, Lingui y React Intl. Las cuatro renderizan traducciones y les dan formato, pero solo gt-react también las genera a partir de textos escritos inline en tu JSX. Elige react-i18next si quieres conservar los catálogos y plugins de i18next, Lingui si buscas extracción a catálogos compilados y React Intl si prefieres FormatJS y el formato de mensajes ICU. - [Redirecciones de idioma y SEO: ¿URL, cookie o Accept-Language?](https://generaltranslation.com/es/kb/locale-routing-seo.mdx): Deja que la URL determine el idioma de cada página que quieras indexar, porque Googlebot no envía la cabecera Accept-Language y rastrea sobre todo desde direcciones de EE. UU. Recurre a la preferencia guardada en una cookie y, en su defecto, a Accept-Language solo para decidir adónde redirige una raíz neutral como /, mediante una redirección temporal 302 o 307. - [¿Cómo traduzco una aplicación de React?](https://generaltranslation.com/es/kb/translate-react-app.mdx): Traducir una aplicación de React significa internacionalizar sus componentes para que se rendericen en el idioma del usuario y, después, traducir cada cadena a todos los idiomas que admitas. gt-react de General Translation traduce JSX en el mismo documento con el componente `<T>`, y npx gt translate genera un archivo por idioma. ## Previous and next questions - Previous question: [¿Qué hace el agente Locadex?](https://generaltranslation.com/es/kb/what-is-locadex.mdx) - Next question: [¿Cómo agrego i18n a una aplicación de Next.js con Pages Router?](https://generaltranslation.com/es/kb/add-i18n-to-nextjs-pages-router.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.