# General Translation React SDKs (gt-react, gt-next, gt-react-native): Inicio rápido de TanStack Start
URL: https://generaltranslation.com/es/docs/react/tanstack-start-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Agrega General Translation a una app de TanStack Start con gt-tanstack-start y traduce tu primer contenido.

`gt-tanstack-start` añade internacionalización automática a las apps de TanStack Start. Inicializas General Translation en el punto de entrada del enrutador, resuelves la configuración regional de la solicitud y cargas [`GTProvider`](/docs/react/reference/components/gt-provider) desde un loader de ruta.

Usa este inicio rápido para apps de TanStack Start. Para una SPA de React sencilla, usa el [Inicio rápido de React](/docs/react/react-quickstart).

<Callout type="warn">
  **Advertencia:** `gt-tanstack-start` es experimental y puede incluir cambios incompatibles. Aún no se recomienda para uso en producción.
</Callout>

Ejecuta [`npx gt@latest init`](/docs/cli/reference/commands/init) desde la raíz de la app para automatizar la configuración. El asistente instala el runtime, crea el loader de traducciones y el middleware, inicializa el enrutador y configura la ruta raíz. No modifica los archivos que no reconoce e indica las acciones manuales que queden pendientes; esta guía explica cómo hacer la misma configuración a mano.

## inicio rápido [#quickstart]

Instala los paquetes, crea un archivo de configuración y un cargador de traducciones, agrega middleware de solicitud, inicializa el enrutador, configura la ruta raíz, marca el contenido para traducir y genera las traducciones.

### 1. Instala `gt-tanstack-start`

Instala `gt-tanstack-start` y `gt-react` como dependencias, y la [CLI de `gt`](/docs/cli/quickstart) como dependencia de desarrollo. `gt-react` es necesario directamente para que la CLI pueda detectar los componentes [`<T>`](/docs/react/reference/components/t) en tu código fuente.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-tanstack-start gt-react && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-tanstack-start gt-react && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-tanstack-start gt-react && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-tanstack-start gt-react && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

`gt-tanstack-start` solo es compatible con 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.*

### 2. Crea `gt.config.json`

Crea un archivo `gt.config.json` en la raíz de tu proyecto. Indica el idioma de origen, las configuraciones regionales de destino y dónde se guardan los archivos de traducción.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

* `defaultLocale` — el idioma en el que está escrita tu app.
* `locales` — los idiomas a los que se traducirá. Elígelos entre las [configuraciones regionales admitidas](/docs/platform/dashboard/reference/supported-locales).
* `files.gt.output` — donde el CLI guarda los archivos de traducción. Mantenlos en `src/` para que Vite pueda importarlos; los archivos de `public/` no se resolverán.

### 3. Crea un cargador de traducciones

Crea un archivo `loadTranslations.ts` que importe en runtime el archivo de traducción correspondiente a una configuración regional.

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

### 4. Agrega el middleware de solicitud

Crea `src/start.ts` y registra [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) como middleware global de solicitud. Conserva el middleware de CSRF de TanStack Start cuando definas una instancia `start` personalizada.

```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 limita la configuración regional, la región y la configuración de internacionalización al ámbito de cada solicitud para que las funciones del servidor usen el idioma correcto. Completa la inicialización en el siguiente paso antes de iniciar el servidor de desarrollo.

### 5. Inicializa General Translation y configura la ruta raíz

Llama a [`initializeGT`](/docs/react/tanstack-start/setup#initialize) una vez a nivel de módulo en `src/router.tsx`. Añade las importaciones y el inicializador a tu archivo de enrutador 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 con [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) y carga una instantánea de traducciones en el loader de `src/routes/__root.tsx`. Pasa `locale` y `translations` a [`GTProvider`](/docs/react/reference/components/gt-provider).

```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>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) lee la configuración regional con alcance de solicitud en el servidor y la configuración regional del navegador inicializada en el cliente. [`GTProvider`](/docs/react/reference/components/gt-provider) requiere tanto `locale` como `translations`.

<Callout type="warn">
  **Advertencia:** Estos archivos de traducción (`src/_gt/[locale].json`) no existen hasta que los crees. La configuración regional predeterminada se sigue renderizando, pero seleccionar una configuración regional de destino en el selector de idioma devuelve un HTTP 500 hasta que existan los archivos. Para crearlos primero, ejecuta [`npx gt generate`](/docs/cli/reference/commands/generate) (no requiere API Key), [`npx gt translate`](/docs/cli/reference/commands/translate) (con credenciales) o añade archivos `{}` vacíos en `src/_gt/[locale].json`.
</Callout>

### 6. Marcar el contenido para su traducción

Envuelve el JSX con el componente [`<T>`](/docs/react/reference/components/t) para traducirlo en el mismo documento. Importa [`<T>`](/docs/react/reference/components/t) y [`useGT`](/docs/react/reference/hooks/use-gt) desde `gt-react` para que la CLI los detecte al analizar tu 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>
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) devuelve la función de traducción directamente, así que llámala como `const gt = useGT();`.

### 7. Generar traducciones

Inicia sesión con [`gt login`](/docs/cli/reference/commands/login), configura el [`projectId`](/docs/cli/reference/config#project-id) de tu proyecto existente en `gt.config.json` o `GT_PROJECT_ID` en el entorno, y traduce:

```bash
npx gt login
GT_PROJECT_ID=your-project-id npx gt translate
```

Agrega el comando a tu script de compilación para que las compilaciones de producción siempre cuenten con traducciones actualizadas:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && vite build"
  }
}
```

<Callout type="info">
  **Nota:** En CI, proporciona una `GT_API_KEY` con permisos propios y el mismo ID de proyecto a través de la configuración de secretos. Usa [`gt init`](/docs/cli/reference/commands/init) por separado si necesitas que se te guíe en la selección o creación del proyecto. (Consulta [credenciales de la CLI](/docs/cli/guides/configuring#credentials)).
</Callout>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

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