# 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 progetto con il permesso di traduzione a runtime.

**Prerequisiti:**

* Un'app React a pagina singola configurata con la [SPA Quickstart](/docs/react/react-spa-quickstart)
* Una [chiave API di progetto](/docs/platform/dashboard/reference/api-keys#create-project-keys) che inizia con `gtx-api-`, con **Runtime translation** abilitato

<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

In **Project &gt; API Keys**, crea una chiave con **Runtime translation** attivato. Funzionano anche le chiavi con accesso completo. Per ridurre al minimo i rischi, consigliamo autorizzazioni **Custom** con **Runtime translation** impostato su **Enabled** e ogni altra risorsa impostata su **None**.

Aggiungi l&#39;ID progetto e la chiave del progetto a `.env.local`, quindi passali alla funzione di inizializzazione. L&#39;SDK usa ancora l&#39;impostazione `devApiKey` per attivare l&#39;hot reload in sviluppo:

<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 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:** le chiavi API possono essere usate nel codice client servito dal tuo server di sviluppo locale. Non includere mai una chiave API nei bundle client distribuiti, indipendentemente dalle sue autorizzazioni. Per ridurre al minimo i rischi, è consigliabile limitare le chiavi di sviluppo locale a **Runtime translation**.
</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.