# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configurar una SPA de Rolldown
URL: https://generaltranslation.com/es/docs/react/guides/spa/configuring-rolldown-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Cómo configurar gt-react en una aplicación React de una sola página basada en Rolldown.

Configura el runtime de la aplicación y, opcionalmente, empaqueta los catálogos de traducción generados con tu compilación de Rolldown.

Esta guía prepara el runtime de la aplicación. Marca por separado el contenido dirigido al usuario para su traducción.

## Configuración de una SPA de React con Rolldown [#setup]

Inicializa `gt-react` antes de que se ejecute el punto de entrada de la aplicación.

### 1. Instala gt-react

Instala la versión más reciente de `gt-react` con el administrador de paquetes preferido del repositorio. Si ya está instalado, omite este paso.

### 2. Agrega un archivo `gt.config.json` en la raíz del proyecto

Agrega un archivo `gt.config.json` en la raíz del proyecto. Este archivo contendrá la configuración del paquete `gt-react`.

Las configuraciones regionales ya presentes en el proyecto o proporcionadas a la tarea de configuración son las que prevalecen. Conserva los valores existentes de `locales` y `defaultLocale`. Los valores siguientes son solo ejemplos. Si el proyecto no tiene una configuración regional, no deduzcas los requisitos de configuración regional a partir de estos ejemplos.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"]
}
```

El campo opcional [`src`](/docs/cli/reference/config#src) indica los archivos de origen que GT analiza en busca de contenido inline; si se omite, se usan de forma predeterminada estos patrones glob de JavaScript y TypeScript en `src`, `app`, `pages` y `components`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. Inicializa la biblioteca

Inicializa la biblioteca con [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) antes de que la aplicación se renderice o importe módulos que usen funciones de traducción a nivel de módulo.

Crea un archivo de bootstrap junto al archivo de entrada existente de la aplicación. En este ejemplo, el archivo de entrada original es `src/main.tsx` y el nuevo archivo de bootstrap es `src/index.ts`. Configura el `input` existente de Rolldown para que apunte al archivo de bootstrap. Conserva todos los demás ajustes de compilación.

```js title="rolldown.config.mjs"
export default {
  // ...las opciones existentes del proyecto
  input: 'src/index.ts',
};
```

Si el HTML de desarrollo hace referencia directamente a la entrada de origen, actualízala también:

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

Luego, inicializa GT e importa dinámicamente la entrada original solo cuando haya finalizado la inicialización. La aplicación de referencia de Rolldown genera ESM y admite `await` de nivel superior:

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

await initializeGTSPA(gtConfig);

await import('./main'); // renderiza la aplicación solo una vez que GT esté listo
```

Si el formato de salida o el destino actuales de Rolldown no admiten `await de nivel superior`, no los modifiques solo para esta configuración. Usa una función de bootstrap asíncrona en su lugar:

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

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## Carga de traducciones [#translations]

Cuando se llama a [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) sin una función [`loadTranslations`](/docs/react/reference/functions/load-translations), el runtime carga las traducciones desde la CDN de General Translation solo cuando hay un [`projectId`](/docs/react/reference/config#project-id) disponible. Para incluir catálogos en el bundle de la aplicación, configura una ruta de salida y un cargador compatible. Los pasos siguientes usan `src/_gt/[locale].json`.

### 1. Actualiza la configuración

Configura `files.gt.output` con la ubicación donde la CLI debe escribir los archivos de traducción generados.

Solo agrega o combina la configuración `files.gt.output`. Conserva los valores existentes de `locales` y `defaultLocale` del proyecto; los valores que se muestran a continuación son ejemplos y no deben sustituir las configuraciones regionales del proyecto.

Por lo general, en una aplicación basada en Rolldown, las traducciones se almacenarán en el directorio `src/_gt`. Esto permite que Rolldown incluya los módulos de traducción en el bundle de la aplicación.

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

### 2. Añade los archivos auxiliares

Crea un archivo JSON vacío para cada configuración regional de destino ya configurada en `gt.config.json`, excepto la configuración regional predeterminada. Estos archivos auxiliares permiten resolver las importaciones antes de que existan los bundles de traducción. Los archivos `fr` y `zh` de abajo ilustran la configuración de ejemplo de esta guía; crea en su lugar archivos para las configuraciones regionales de destino realmente configuradas en el proyecto. Si no hay configuraciones regionales de destino configuradas, no inventes configuraciones regionales ni crees archivos de marcador de posición.

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />

      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. Añade el cargador

Crea `src/loadTranslations.ts` para cargar las traducciones. Debe resolverse en la misma ubicación de salida configurada en `files.gt.output`.

Enumera explícitamente cada configuración regional de destino en `translationLoaders`. Cada cargador debe usar una ruta de importación literal para que Rolldown pueda detectar y generar cada archivo de traducción durante la compilación. Las entradas `fr` y `zh` siguientes coinciden con la configuración de ejemplo de esta guía; usa en su lugar las configuraciones regionales de destino realmente configuradas en el proyecto.

```ts title="src/loadTranslations.ts"
const translationLoaders = {
  fr: () => import('./_gt/fr.json'),
  zh: () => import('./_gt/zh.json'),
};

export default async function loadTranslations(locale: string) {
  try {
    const loader =
      translationLoaders[locale as keyof typeof translationLoaders];
    if (!loader) {
      console.warn(`No translations found for locale "${locale}"`);
      return {};
    }
    const translations = await loader();
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for locale "${locale}"`, error);
    return {};
  }
}
```

### 4. Actualice el inicializador

Actualice el inicializador para usar el nuevo cargador. Conserve la forma de bootstrap con await en el nivel superior o con una función asíncrona que use la aplicación.

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

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

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