# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA guía de inicio rápido
URL: https://generaltranslation.com/es/docs/react/react-spa-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Agrega varios idiomas a una aplicación React de una sola página.

Al final de esta guía, tu aplicación React de una sola página mostrará contenido en varios idiomas, con un selector de idioma con el que tus usuarios podrán interactuar.

En una aplicación de una sola página, `gt-react` se ejecuta completamente en el navegador: lo inicializas una sola vez al arrancar con [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa), y no necesitas un componente proveedor.

**Requisitos previos:**

* Una aplicación React renderizada en el cliente (Vite, webpack o similar)
* Node.js 18+

Tu sistema de compilación puede requerir una versión más reciente de Node.js. Por ejemplo, Vite 8 requiere `^20.19.0 || >=22.12.0`.

<Callout type="info">
  **Consejo:** Ejecuta `npx gt@latest` para configurar el arranque de Vite y la carga de traducciones con el [Asistente de configuración](/docs/cli/quickstart). Esta guía explica la configuración manual.
</Callout>

<Callout type="info">
  **Nota:** Si tu aplicación se renderiza en el servidor, sigue la [guía de inicio rápido de React](/docs/react/react-quickstart) en su lugar.
</Callout>

## Elige tu empaquetador [#bundlers]

Los pasos siguientes usan Vite como ejemplo principal. Si utilizas otro sistema de compilación, consulta
su guía de configuración para el punto de entrada, el arranque y el cargador de traducciones:

<Cards>
  <Card title="Vite" href="/docs/react/guides/spa/configuring-vite-spa">
    Configura la entrada HTML de Vite y la carga de traducciones.
  </Card>

  <Card title="webpack" href="/docs/react/guides/spa/configuring-webpack-spa">
    Configura el punto de entrada de webpack y el contexto de traducción.
  </Card>

  <Card title="esbuild" href="/docs/react/guides/spa/configuring-esbuild-spa">
    Configura los puntos de entrada de esbuild y los contenidos alternativos para el destino de salida.
  </Card>

  <Card title="Rollup" href="/docs/react/guides/spa/configuring-rollup-spa">
    Configura la entrada de Rollup y un mapa de configuraciones regionales analizable estáticamente.
  </Card>

  <Card title="Rolldown" href="/docs/react/guides/spa/configuring-rolldown-spa">
    Configura la entrada de Rolldown y un mapa de configuraciones regionales analizable estáticamente.
  </Card>

  <Card title="Bazel" href="/docs/react/guides/spa/configuring-bazel-spa">
    Declara el arranque, la configuración, el paquete y las traducciones como entradas de Bazel.
  </Card>
</Cards>

Después de la configuración, consulta [Internacionalización de una SPA de React](/docs/react/guides/spa/internationalizing-react-spa)
para obtener indicaciones específicas para SPA sobre JSX, cadenas, selección de configuración regional y validación.

## Guía de inicio rápido [#quickstart]

### 1. Instala los paquetes

`gt-react` es la biblioteca que habilita las traducciones en tu aplicación. `gt` es la CLI que prepara tus traducciones.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react
    npm i -D gt
    ```
  </Tab>

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

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

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

### 2. Crea un archivo de configuración de traducción

Crea un archivo **`gt.config.json`** en la raíz de tu proyecto. Esto le indica a la biblioteca qué idiomas admite tu proyecto:

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

* **`defaultLocale`** — el idioma en el que está escrita tu app (tu idioma de origen).
* **`locales`** — los idiomas a los que quieres traducirla. Elige cualquiera de la [lista de configuraciones regionales compatibles](/docs/platform/dashboard/reference/supported-locales).
* **`files`** — indica al CLI dónde guardar los archivos de traducción. La ruta `output` debe coincidir con la ruta de importación de tu función [`loadTranslations`](/docs/react/reference/functions/load-translations) (Paso 3).

De forma predeterminada, el CLI analiza los archivos JavaScript y TypeScript dentro de `src`, `app`, `pages` y `components`. Configura [`src`](/docs/cli/reference/config#src) cuando tu código fuente esté en otra ubicación.

<Callout type="info">
  **Nota:** Los empaquetadores como Vite importan los archivos de traducción como módulos, por lo que los archivos de traducción deben estar dentro de `src/`.
</Callout>

### 3. Crea un cargador de traducciones

En una SPA, `gt-react` necesita una función para cargar archivos de traducción en el navegador en tiempo de ejecución. Crea un archivo [`loadTranslations`](/docs/react/reference/functions/load-translations):

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for ${locale}`);
    return {};
  }
}
```

Esta función carga archivos JSON de traducción desde tu directorio `src/_gt/`. La CLI genera estos archivos cuando ejecutas [`npx gt translate`](/docs/cli/reference/commands/translate).

<Callout type="info">
  **Rollup:** Rollup sin complementos no puede analizar la importación totalmente dinámica anterior. Usa en su lugar el [mapa estático de cargadores de configuraciones regionales](/docs/react/guides/developing-spa-translations#setup).
</Callout>

<Accordions>
  <Accordion title="¿Quieres mantener las traducciones de Create React App en public?">
    Create React App puede usar el cargador del directorio de origen anterior. Si prefieres mantener las traducciones generadas en `public/`, cambia la salida de la CLI a `public/_gt/[locale].json`:

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

    Carga el archivo mediante HTTP con `PUBLIC_URL`:

    ```ts title="src/loadTranslations.ts"
    export default async function loadTranslations(locale: string) {
      try {
        const response = await fetch(
          `${process.env.PUBLIC_URL}/_gt/${locale}.json`
        );
        if (!response.ok) throw new Error('Translation file not found');
        return await response.json();
      } catch {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }
    ```
  </Accordion>
</Accordions>

### 4. Inicializa la biblioteca

Llama a **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** una sola vez al inicio, antes de que se renderice la aplicación. Recibe tu configuración y el cargador de traducciones, determina la configuración regional del usuario y carga las traducciones correspondientes.

La forma más robusta de hacerlo es usar un pequeño módulo de entrada que primero inicialice GT y luego cargue el resto de la aplicación. Esto te permite traducir contenido a nivel de módulo.

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({
  ...gtConfig,
  loadTranslations,
});

await import('./main'); // renderizar la app solo después de que GT esté listo
```

<Accordions>
  <Accordion title="¿Usas CommonJS?">
    CommonJS no admite `await` en el nivel superior. Coloca la inicialización dentro de una función de arranque asíncrona y luego importa la aplicación de forma dinámica. Esto mantiene el límite asíncrono necesario para las llamadas a [`t()`](/docs/react/reference/functions/t-function) a nivel de módulo.

    ```js title="src/index.js"
    const { initializeGTSPA } = require('gt-react');
    const gtConfig = require('../gt.config.json');

    async function loadTranslations(locale) {
      try {
        return require(`./_gt/${locale}.json`);
      } catch (error) {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }

    async function start() {
      await initializeGTSPA({
        ...gtConfig,
        loadTranslations,
      });

      await import('./main');
    }

    start().catch(console.error);
    ```

    <Callout type="warn">
      **Advertencia:** No uses `require` para `main` antes de la inicialización. Al hacerlo, se evalúan las llamadas a [`t()`](/docs/react/reference/functions/t-function) a nivel de módulo antes de que las traducciones estén listas.
    </Callout>
  </Accordion>
</Accordions>

```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

Luego, actualiza la etiqueta `script` de tipo módulo en tu `index.html` para que apunte al nuevo punto de entrada: cambia su `src` de `/src/main.tsx` a `/src/index.ts`.

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) se ejecuta una sola vez al iniciar: la configuración es inmutable durante toda la vida útil de la aplicación. Una vez que se completa, las traducciones pueden resolverse en cualquier módulo. **No necesitas envolver tu aplicación en un proveedor.**

<Accordions>
  <Accordion title="¿Usas Create React App?">
    Create React App bloquea las importaciones desde fuera de `src/` y no habilita `await` en el nivel superior. Conserva el archivo raíz `gt.config.json` para la CLI, cambia el nombre de tu punto de entrada existente `src/index.tsx` a `src/main.tsx` y luego crea este nuevo punto de entrada:

    ```ts title="src/index.ts"
    import { initializeGTSPA } from 'gt-react';
    import loadTranslations from './loadTranslations';

    async function start() {
      await initializeGTSPA({
        defaultLocale: 'en',
        locales: ['es', 'fr', 'ja'],
        loadTranslations,
      });

      await import('./main');
    }

    start().catch(console.error);
    ```

    Mantén estos valores de configuración regional sincronizados con la configuración raíz cada vez que agregues o elimines un idioma. Deja `public/index.html` sin cambios; Create React App ya carga `src/index`.
  </Accordion>
</Accordions>

<Callout type="info">
  **Consejo:** Sigue [Desarrollo con traducciones para SPA](/docs/react/guides/developing-spa-translations) para agregar el compilador y las credenciales de desarrollo.
</Callout>

### 5. Marcar el contenido para traducir

Ahora, envuelve cualquier texto que quieras traducir con el componente **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) significa &quot;traducir&quot;:

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

Puedes envolver tanto o tan poco JSX como quieras dentro de [`<T>`](/docs/react/reference/components/t). Todo lo que haya dentro —texto, elementos anidados e incluso el formato— se traduce como una sola unidad.

Para las cadenas fuera de los componentes de React, usa **[`t()`](/docs/react/reference/functions/t-function)**. Funciona a nivel de módulo porque [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) carga las traducciones antes que el resto de tu aplicación:

```ts title="src/navigation.ts"
import { t } from 'gt-react';

export const navigation = [
  { label: t('Home'), href: '/' },
  { label: t('About'), href: '/about' },
];
```

### 6. Añade un selector de idioma

Añade un **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** para que los usuarios cambien de idioma:

```tsx title="src/components/Welcome.tsx"
import { T, LocaleSelector } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`LocaleSelector`](/docs/react/reference/components/locale-selector) renderiza un menú desplegable con los idiomas de tu `gt.config.json`.

Cuando el usuario selecciona un idioma, `gt-react` guarda la elección en la cookie `generaltranslation.locale` y recarga la página; después, [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) se vuelve a ejecutar y carga las traducciones de la nueva configuración regional antes de que se renderice la aplicación.

### 7. Autentícate y traduce

Antes de traducir, autentícate con General Translation:

```bash
npx gt auth
```

Sigue las instrucciones para crear una cuenta o iniciar sesión. Cuando se te pida el tipo de clave, elige una clave de producción. El comando genera una clave de API y el ID del proyecto, y luego los añade a `.env.local` en la raíz de tu proyecto:

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="gtx-api-your-production-key"
```

<Callout type="warn">
  **Advertencia:** No hagas commit de `.env.local` ni expongas `GT_API_KEY` en el código del navegador.
</Callout>

Luego, ejecuta el comando translate para generar archivos de traducción para cada configuración regional configurada:

```bash
npx gt translate
```

La CLI analiza tu aplicación, traduce su contenido y escribe los resultados en la ruta de salida de `gt.config.json`. Vuelve a ejecutarla cada vez que cambie tu contenido fuente.

### 8. Ejecutar y verificar

Renderiza el componente de ejemplo desde tu aplicación:

```tsx title="src/App.tsx"
import Welcome from './components/Welcome';

export default function App() {
  return <Welcome />;
}
```

Inicia el servidor de desarrollo de tu aplicación (por ejemplo, `npm run dev` en Vite), abre su URL local y selecciona `es`, `fr` o `ja`. Comprueba que la página se recargue y que el encabezado muestre la traducción seleccionada.

## Solución de problemas [#troubleshooting]

<Accordions>
  <Accordion title="El idioma no cambia al usar el menú desplegable">
    Confirma que las cookies del navegador estén habilitadas, que la configuración regional seleccionada aparezca en `gt.config.json` y que [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) se resuelva antes de que se cargue el módulo de entrada de la aplicación.
  </Accordion>

  <Accordion title="Algunas traducciones son inexactas">
    Un texto ambiguo puede dar lugar a traducciones inexactas. Por ejemplo, &quot;apple&quot; podría referirse a la fruta o a la empresa. Agrega una prop `$context` para dar más contexto:

    ```jsx
    <T $context="the technology company">Apple</T>
    ```

    Tanto [`<T>`](/docs/react/reference/components/t) como [`useGT()`](/docs/react/reference/hooks/use-gt) admiten la opción `$context`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/developing-spa-translations
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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