# General Translation React SDKs (gt-react, gt-next, gt-react-native): Desarrollo con traducción para SPA
URL: https://generaltranslation.com/es/docs/react/guides/developing-spa-translations.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Cómo previsualizar las traducciones de General Translation mientras desarrollas una aplicación React de una sola página.

Las traducciones de desarrollo te permiten previsualizar el contenido traducido mientras editas tu SPA. Requieren el compilador de GT y una clave de API de proyecto con permiso de traducción en tiempo de ejecución.

**Requisitos previos:**

* Una aplicación React de una sola página configurada con la [SPA Quickstart](/docs/react/react-spa-quickstart)
* Una [clave de API de proyecto](/docs/platform/dashboard/reference/api-keys#create-project-keys) que comience con `gtx-api-`, con **Runtime translation** habilitado

<Callout type="warn">
  **Limitación de CommonJS:** La recarga en caliente durante el desarrollo requiere ESM porque el compilador inserta `await` en el nivel superior. No funciona en aplicaciones compiladas como CommonJS. Las traducciones de producción siguen funcionando con el patrón de inicio de CommonJS de la [SPA Quickstart](/docs/react/react-spa-quickstart).
</Callout>

## Configuración [#setup]

### 1. Instala el compilador

Instala `@generaltranslation/compiler` como dependencia de desarrollo:

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

  <Tab value="yarn">
    ```bash
    yarn add --dev @generaltranslation/compiler
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev @generaltranslation/compiler
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev @generaltranslation/compiler
    ```
  </Tab>
</Tabs>

### 2. Añade el plugin del compilador

Activa la recarga en caliente en desarrollo en la config compartida por la CLI y el compilador:

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json",
      "parsingFlags": {
        "devHotReload": true
      }
    }
  }
}
```

A continuación, añade el plugin para tu empaquetador.

<Callout type="info">
  **Bazel y Rolldown:** El compilador no proporciona adaptadores dedicados para estos sistemas de compilación. [Almacena las traducciones localmente](/docs/react/guides/storing-translations) en lugar de depender de la recarga en caliente impulsada por el compilador.
</Callout>

<Tabs items={['Vite', 'webpack', 'Rollup', 'Rspack', 'esbuild']}>
  <Tab value="Vite">
    ```ts title="vite.config.ts"
    import react from '@vitejs/plugin-react';
    import { vite as gtCompiler } from '@generaltranslation/compiler'; // [!code highlight]
    import { defineConfig } from 'vite';

    export default defineConfig({
      plugins: [react(), gtCompiler()], // [!code highlight]
    });
    ```

    `gtCompiler()` carga automáticamente el `gt.config.json` de la raíz.
  </Tab>

  <Tab value="webpack">
    Instala `dotenv` como dependencia de desarrollo para que webpack pueda leer `.env` y `.env.local` y, a continuación, añade el plugin del compilador antes que el resto de tus plugins. Usa `DefinePlugin` para exponer al código del navegador solo las credenciales de desarrollo:

    ```js title="webpack.config.mjs"
    import { webpack as gtCompiler } from '@generaltranslation/compiler';
    import dotenv from 'dotenv';
    import webpack from 'webpack';
    import gtConfig from './gt.config.json' with { type: 'json' };

    dotenv.config({ path: '.env' });
    dotenv.config({ path: '.env.local', override: true });

    export default (_env, argv) => {
      const isProduction = (argv.mode ?? 'production') === 'production';

      return {
        // Mantén tu configuración actual de webpack.
        plugins: [
          gtCompiler({ ...gtConfig }),
          new webpack.DefinePlugin({
            'process.env.GT_PROJECT_ID': JSON.stringify(
              isProduction ? '' : (process.env.GT_PROJECT_ID ?? '')
            ),
            'process.env.GT_DEV_API_KEY': JSON.stringify(
              isProduction ? '' : (process.env.GT_DEV_API_KEY ?? '')
            ),
          }),
        ],
      };
    };
    ```

    Consulta el [ejemplo completo de webpack de `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/webpack-spa) para ver loaders, archivos de traducción locales y la configuración del servidor de desarrollo.
  </Tab>

  <Tab value="Rollup">
    Registra el compilador antes que tus otros plugins de Rollup:

    ```js title="rollup.config.mjs"
    import { rollup as gtCompiler } from '@generaltranslation/compiler';

    export default {
      input: 'src/index.ts',
      plugins: [
        gtCompiler(),
        // Tus otros plugins de Rollup
      ],
    };
    ```

    Rollup no puede analizar una importación de traducciones totalmente dinámica. Enumera cada configuración regional con un especificador de importación estático:

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

    export default async function loadTranslations(locale: string) {
      const loader =
        translationLoaders[locale as keyof typeof translationLoaders];
      return loader ? (await loader()).default : {};
    }
    ```

    Rollup sin extensiones no proporciona la integración de credenciales de desarrollo mostrada para Vite y webpack. Vuelve a generar los archivos de traducción locales cuando cambie el contenido fuente. Consulta el [ejemplo completo de Rollup de `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/rollup-spa).
  </Tab>

  <Tab value="Rspack">
    Añade el adaptador de Rspack a tus plugins:

    ```js title="rspack.config.mjs"
    import { rspack as gtCompiler } from '@generaltranslation/compiler';

    export default {
      plugins: [gtCompiler()],
    };
    ```

    La traducción de desarrollo también requiere exponer `GT_PROJECT_ID` y `GT_DEV_API_KEY` al código del navegador sin incluir ninguno de los dos valores en los bundles de producción.
  </Tab>

  <Tab value="esbuild">
    Añade el adaptador de esbuild al array `plugins`:

    ```js title="build.mjs"
    import { build } from 'esbuild';
    import { esbuild as gtCompiler } from '@generaltranslation/compiler';

    await build({
      entryPoints: ['src/index.ts'],
      bundle: true,
      format: 'esm',
      outdir: 'dist',
      plugins: [gtCompiler()],
    });
    ```

    *Nota: El adaptador de esbuild no admite la inyección automática de JSX. Envuelve explícitamente el JSX traducible o usa otro adaptador cuando se requiera `enableAutoJsxInjection`.*
  </Tab>
</Tabs>

Consulta el [ejemplo completo de Vite de `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/vite-spa) para ver una configuración completa de Vite.

### 3. Añade credenciales de desarrollo

En **Project &gt; API Keys**, crea una clave con **Runtime translation** habilitado. Las claves de acceso completo también funcionan. Para minimizar el riesgo, recomendamos permisos **Custom** con **Runtime translation** en **Enabled** y todos los demás recursos en **None**.

Agrega el ID del Project y la clave de Project a `.env.local` y luego pásalos a tu función de inicialización. El SDK sigue usando la opción `devApiKey` para habilitar la recarga en caliente en desarrollo:

<Tabs items={['Vite', 'webpack']}>
  <Tab value="Vite">
    ```bash title=".env.local"
    VITE_GT_PROJECT_ID="your-project-id"
    VITE_GT_DEV_API_KEY="gtx-api-your-runtime-key"
    ```

    ```ts
    await initializeGTSPA({
      ...gtConfig,
      projectId: import.meta.env.VITE_GT_PROJECT_ID,
      devApiKey: import.meta.env.DEV
        ? import.meta.env.VITE_GT_DEV_API_KEY
        : undefined,
      loadTranslations,
    });
    ```
  </Tab>

  <Tab value="webpack">
    ```bash title=".env.local"
    GT_PROJECT_ID="your-project-id"
    GT_DEV_API_KEY="gtx-api-your-runtime-key"
    ```

    ```ts
    await initializeGTSPA({
      ...gtConfig,
      projectId: process.env.GT_PROJECT_ID,
      devApiKey: process.env.GT_DEV_API_KEY,
      loadTranslations,
    });
    ```

    La configuración de webpack anterior reemplaza ambos valores por cadenas vacías en las compilaciones de producción, por lo que las credenciales de desarrollo no se incluyen en el bundle de producción.
  </Tab>
</Tabs>

<Callout type="warn">
  **Solo para desarrollo:** las claves de API pueden usarse en código de cliente servido por tu servidor de desarrollo local. Nunca incluyas ninguna clave de API en bundles de cliente desplegados, sin importar sus permisos. Se recomienda restringir las claves de desarrollo local a **Runtime translation** para minimizar el riesgo.
</Callout>

### 4. Empieza a desarrollar

Inicia tu servidor de desarrollo y cambia a una configuración regional distinta de la predeterminada. Cuando editas contenido traducible, el compilador registra el cambio y `gt-react` solicita una traducción de desarrollo actualizada.

## Next steps

- /docs/react/guides/storing-translations
- /docs/react/guides/configuring
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales

## Sitemap

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