# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configura TanStack Start
URL: https://generaltranslation.com/es/docs/react/tanstack-start/setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Registra el middleware de solicitud de General Translation, inicializa una app de TanStack Start, resuelve la configuración regional e hidrata el proveedor.

`gt-tanstack-start` usa middleware global de solicitud, inicialización del enrutador a nivel de módulo y un loader de ruta raíz. El middleware crea un estado local por solicitud para el código del servidor, mientras que el loader raíz hidrata [`<GTProvider>`](/docs/react/reference/components/gt-provider) con la configuración regional y las traducciones.

Esta página explica la configuración específica de TanStack Start. Para ver el proceso completo, incluida la instalación y la CLI, sigue la [Quickstart de TanStack Start](/docs/react/tanstack-start-quickstart).

<Callout type="warn">
  **Advertencia:** `gt-tanstack-start` es experimental y puede introducir cambios incompatibles.
</Callout>

*Nota: `gt-tanstack-start` es solo para ESM. Usa la sintaxis `import` en lugar de `require()` de CommonJS.*

*Nota: Esta configuración requiere `gt-tanstack-start` 11.1.5 o una versión posterior para que [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) se resuelva desde la entrada principal del paquete en las compilaciones de cliente.*

## Cargar traducciones [#load-translations]

Crea una función [`loadTranslations`](/docs/react/reference/functions/load-translations) que importe el archivo de traducción correspondiente a una configuración regional. Mantén los archivos dentro de `src/` para que Vite pueda importarlos.

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./src/_gt/${locale}.json`);
  return translations.default;
}
```

La CLI genera estos archivos al ejecutar [`npx gt translate`](/docs/cli/reference/commands/translate).

## Registrar el middleware de solicitud [#middleware]

Crea `src/start.ts` y registra [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) como middleware global para las solicitudes. Mantén el middleware de Cross-Site Request Forgery (CSRF) de TanStack Start al definir una instancia personalizada de `start`.

```ts title="src/start.ts"
import { createCsrfMiddleware, createStart } from '@tanstack/react-start';
import { gtMiddleware } from 'gt-tanstack-start';

const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware, gtMiddleware],
}));
```

El middleware resuelve la configuración regional, la región y la configuración de internacionalización una vez por cada solicitud. Guarda la configuración regional resuelta en la cookie de configuración regional y pone el estado de la solicitud a disposición de las [funciones de runtime isomórficas](/docs/react/tanstack-start/using-server-functions) en el servidor.

## Inicializa y resuelve la configuración regional [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize), [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) y [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) se importan desde `gt-tanstack-start`:

* **[`initializeGT`](/docs/react/reference/config#initialize)** — llámalo una vez en el ámbito del módulo en `src/router.tsx`. Expande tu `gt.config.json` y pasa [`loadTranslations`](/docs/react/reference/functions/load-translations).
* **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — devuelve la configuración regional desde el ámbito activo del middleware en el servidor y desde el almacén de condiciones del navegador inicializado en el cliente.
* **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — carga las traducciones de una configuración regional con el formato que espera [`<GTProvider>`](/docs/react/reference/components/gt-provider), para que el contenido se renderice sin un parpadeo de carga. Consulta la [referencia](/docs/react/reference/functions/get-translations-snapshot).

## Habilitar el enrutamiento por configuración regional [#locale-routing]

El enrutamiento por configuración regional es opcional. Antes de habilitarlo, configura TanStack Router para que acepte tanto la URL sin prefijo de la configuración regional predeterminada, como `/about`, como las URL con prefijo de configuración regional, como `/es/about`.

Puedes agregar un [segmento opcional `/{-$locale}`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters) a tus rutas basadas en archivos o en código, o usar la [opción `rewrite`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite) de TanStack Router para asignar URL públicas con prefijo de configuración regional a tu árbol de rutas existente. Por ejemplo, la ruta opcional `/{-$locale}/about` coincide con `/about`, `/es/about` y `/ja/about`.

Después de que el enrutador acepte ambos formatos de URL, establece `localeRouting` en `true` en `gt.config.json`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "localeRouting": true
}
```

`gt-tanstack-start` no crea ni reestructura las rutas de tu aplicación. La opción le indica que resuelva la configuración regional a partir de un prefijo de ruta admitido y actualice la ruta de acceso cuando cambie la configuración regional. La configuración regional predeterminada permanece sin prefijo, como `/about`, mientras que las demás configuraciones regionales usan un prefijo, como `/es/about`.

En el servidor, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) resuelve la configuración regional a partir de la ruta, luego de la cookie de configuración regional, la cabecera `Accept-Language` y `defaultLocale`. En el cliente, los cambios de configuración regional recargan la ruta de acceso correspondiente y conservan su cadena de consulta y hash.

Se respeta la ruta base de TanStack Router mediante `TSS_ROUTER_BASEPATH`.

## Inicializa el enrutador y configura la ruta raíz [#root-route]

Agrega las importaciones y el inicializador de [`initializeGT`](/docs/react/reference/config#initialize) a 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 });
```

Luego, resuelve la configuración regional y carga la instantánea en el loader de `src/routes/__root.tsx`. Pasa `locale` y `translations` a [`<GTProvider>`](/docs/react/reference/components/gt-provider) en el componente shell.

```tsx title="src/routes/__root.tsx"
import {
  HeadContent,
  Scripts,
  createRootRoute,
} from '@tanstack/react-router';
import {
  GTProvider,
  getLocale,
  getTranslationsSnapshot,
  LocaleSelector,
} from 'gt-tanstack-start';

export const Route = createRootRoute({
  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>
  );
}
```

[`<GTProvider>`](/docs/react/reference/components/gt-provider) requiere aquí tanto `locale` como `translations`, a diferencia de Next.js, donde el servidor los resuelve, o de React Native, donde el proveedor los carga por sí solo.

[`initializeGT`](/docs/react/reference/config#initialize) debe ejecutarse antes de que [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) gestione una solicitud. Completa la configuración del enrutador y de la ruta raíz antes de iniciar el servidor de desarrollo.

## Marca el contenido para traducir [#content]

En los componentes de tus rutas, envuelve el JSX en [`<T>`](/docs/react/reference/components/t) y traduce cadenas con [`useGT`](/docs/react/reference/hooks/use-gt). Impórtalos desde `gt-react` para que la CLI los detecte al analizar el código fuente.

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { T, useGT } from 'gt-react';

export const Route = createFileRoute('/')({ component: Home });

function Home() {
  const gt = useGT();

  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email input field')} />
    </main>
  );
}
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.