# General Translation React SDKs (gt-react, gt-next, gt-react-native): Sviluppare con le traduzioni per SPA
URL: https://generaltranslation.com/it/docs/react/guides/developing-spa-translations.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Come visualizzare in anteprima le traduzioni di General Translation durante lo sviluppo di un'app React a pagina singola.

Le traduzioni di sviluppo ti permettono di visualizzare in anteprima i contenuti tradotti mentre modifichi la tua SPA. Richiedono il compilatore GT e una chiave API di sviluppo.

**Prerequisiti:**

* Un'app React a pagina singola configurata con la [SPA Quickstart](/docs/react/react-spa-quickstart)
* Una chiave API di sviluppo che inizia con `gtx-dev-`

<Callout type="warn">
  **Limitazione di CommonJS:** L&#39;hot reload in sviluppo richiede ESM perché il compilatore inserisce `await` al livello superiore. Non funziona nelle applicazioni compilate come CommonJS. Le traduzioni di produzione continuano comunque a funzionare con il pattern di avvio CommonJS della [SPA Quickstart](/docs/react/react-spa-quickstart).
</Callout>

## Configurazione [#setup]

### 1. Installa il compilatore

Installa `@generaltranslation/compiler` come dipendenza di sviluppo:

<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. Aggiungi il plugin del compilatore

Abilita l&#39;hot reload di sviluppo nella config condivisa tra CLI e compilatore:

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

Quindi aggiungi il plugin per il bundler che usi.

<Callout type="info">
  **Bazel e Rolldown:** il compilatore non fornisce adattatori dedicati per questi sistemi di build. [Archivia le traduzioni localmente](/docs/react/guides/storing-translations) invece di affidarti all&#39;hot reload gestito dal compilatore.
</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()` carica automaticamente il `gt.config.json` nella radice.
  </Tab>

  <Tab value="webpack">
    Installa `dotenv` come dipendenza di sviluppo in modo che webpack possa leggere `.env` e `.env.local`, quindi aggiungi il compilatore prima degli altri plugin. Usa `DefinePlugin` per esporre al codice del browser solo le credenziali di sviluppo:

    ```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 {
        // Mantieni le impostazioni webpack esistenti.
        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 l&#39;[esempio webpack completo di `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/webpack-spa) per loader, file di traduzione locali e impostazioni del server di sviluppo.
  </Tab>

  <Tab value="Rollup">
    Registra il compilatore prima degli altri plugin Rollup:

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

    export default {
      input: 'src/index.ts',
      plugins: [
        gtCompiler(),
        // I tuoi altri plugin Rollup
      ],
    };
    ```

    Rollup non può analizzare un&#39;importazione di traduzione completamente dinamica. Elenca ogni impostazione regionale con uno specificatore di importazione statico:

    ```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 standard non fornisce l&#39;integrazione delle credenziali di sviluppo mostrata per Vite e webpack. Rigenera i file di traduzione locali quando il contenuto sorgente cambia. Consulta l&#39;[esempio Rollup completo di `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/rollup-spa).
  </Tab>

  <Tab value="Rspack">
    Aggiungi l&#39;adattatore Rspack ai plugin:

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

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

    La traduzione di sviluppo richiede anche di esporre `GT_PROJECT_ID` e `GT_DEV_API_KEY` al codice del browser senza includere nessuno dei due valori nei bundle di produzione.
  </Tab>

  <Tab value="esbuild">
    Aggiungi l&#39;adattatore esbuild all&#39;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: l&#39;adattatore esbuild non supporta l&#39;iniezione JSX automatica. Racchiudi esplicitamente il JSX traducibile oppure usa un altro adattatore quando è richiesto `enableAutoJsxInjection`.*
  </Tab>
</Tabs>

Consulta l&#39;[esempio Vite completo di `gt-react`](https://github.com/generaltranslation/gt/tree/main/examples/vite-spa) per una configurazione Vite completa.

### 3. Aggiungi le credenziali di sviluppo

Ottieni una chiave API di sviluppo su [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) oppure esegui:

```bash
npx gt auth
```

Quindi aggiungi l&#39;ID progetto e la chiave API di sviluppo a `.env.local`, quindi passali alla funzione di inizializzazione:

<Tabs items={['Vite', 'webpack']}>
  <Tab value="Vite">
    ```bash title=".env.local"
    VITE_GT_PROJECT_ID="your-project-id"
    VITE_GT_DEV_API_KEY="your-dev-api-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="your-dev-api-key"
    ```

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

    La configurazione di webpack qui sopra sostituisce entrambi i valori con stringhe vuote nelle build di produzione, quindi le credenziali di sviluppo non vengono incluse nel bundle di produzione.
  </Tab>
</Tabs>

<Callout type="warn">
  **Solo per lo sviluppo:** usa una chiave che inizi con `gtx-dev-`. Non esporre mai nel codice del browser una chiave di produzione che inizi con `gtx-api-`.
</Callout>

### 4. Inizia a sviluppare

Avvia il server di sviluppo e passa a un&#39;impostazione regionale diversa da quella predefinita. Quando modifichi contenuti traducibili, il compilatore registra la modifica e `gt-react` richiede una traduzione di sviluppo aggiornata.

## 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.