# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA Quickstart
URL: https://generaltranslation.com/it/docs/react/react-spa-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Aggiungi più lingue a un'applicazione React a pagina singola.

Al termine di questa guida, la tua app React a pagina singola mostrerà contenuti in più lingue, con un selettore di lingua con cui gli utenti potranno interagire.

In un'app a pagina singola, `gt-react` viene eseguito interamente nel browser: lo inizializzi una sola volta all'avvio con [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) e non hai bisogno di un componente provider.

**Prerequisiti:**

* Un'app React con rendering client-side (Vite, webpack o simili)
* Node.js 18+

Il tuo sistema di build potrebbe richiedere una versione più recente di Node.js. Ad esempio, Vite 8 richiede `^20.19.0 || >=22.12.0`.

<Callout type="info">
  **Suggerimento:** Esegui `npx gt@latest` per configurare il bootstrap di Vite e il caricamento delle traduzioni con la [procedura guidata di setup](/docs/cli/quickstart). Questa guida illustra la configurazione manuale.
</Callout>

<Callout type="info">
  **Nota:** Se la tua app esegue il rendering sul server, segui invece la [React Quickstart](/docs/react/react-quickstart).
</Callout>

## Scegli il bundler [#bundlers]

I passaggi seguenti usano Vite come esempio principale. Se utilizzi un altro sistema di build, consulta
la relativa guida alla configurazione del punto di ingresso, del bootstrap e del loader delle traduzioni:

<Cards>
  <Card title="Vite" href="/docs/react/guides/spa/configuring-vite-spa">
    Configura il punto di ingresso HTML di Vite e il caricamento delle traduzioni.
  </Card>

  <Card title="webpack" href="/docs/react/guides/spa/configuring-webpack-spa">
    Configura il punto di ingresso di webpack e il contesto di traduzione.
  </Card>

  <Card title="esbuild" href="/docs/react/guides/spa/configuring-esbuild-spa">
    Configura i punti di ingresso di esbuild e i fallback per la destinazione di output.
  </Card>

  <Card title="Rollup" href="/docs/react/guides/spa/configuring-rollup-spa">
    Configura l&#39;input di Rollup e una mappa delle impostazioni regionali analizzabile staticamente.
  </Card>

  <Card title="Rolldown" href="/docs/react/guides/spa/configuring-rolldown-spa">
    Configura l&#39;input di Rolldown e una mappa delle impostazioni regionali analizzabile staticamente.
  </Card>

  <Card title="Bazel" href="/docs/react/guides/spa/configuring-bazel-spa">
    Dichiara il bootstrap, la configurazione, il package e le traduzioni come input di Bazel.
  </Card>
</Cards>

Dopo la configurazione, consulta [Internazionalizzare una React SPA](/docs/react/guides/spa/internationalizing-react-spa)
per indicazioni specifiche per le SPA su JSX, stringhe, selezione dell&#39;impostazione regionale e convalida.

## Quickstart [#quickstart]

### 1. Installa i pacchetti

`gt-react` è la libreria che gestisce le traduzioni nella tua app. `gt` è il tool CLI che prepara le traduzioni.

<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 file di configurazione della traduzione

Crea un file **`gt.config.json`** nella radice del progetto. Questo indica alla libreria quali lingue sono supportate:

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

* **`defaultLocale`** — la lingua in cui è scritta la tua app (la lingua sorgente).
* **`locales`** — le lingue in cui vuoi tradurre. Scegli quelle che ti servono dall&#39;[elenco delle impostazioni regionali supportate](/docs/platform/dashboard/reference/supported-locales).
* **`files`** — indica alla CLI dove salvare i file di traduzione. Il percorso `output` deve corrispondere al percorso di importazione nella funzione [`loadTranslations`](/docs/react/reference/functions/load-translations) (Passaggio 3).

Per impostazione predefinita, la CLI analizza i file JavaScript e TypeScript in `src`, `app`, `pages` e `components`. Imposta [`src`](/docs/cli/reference/config#src) se il tuo codice sorgente si trova altrove.

<Callout type="info">
  **Nota:** I bundler come Vite importano i file di traduzione come moduli, quindi i file di traduzione devono trovarsi all&#39;interno di `src/`.
</Callout>

### 3. Crea un loader delle traduzioni

In una SPA, `gt-react` ha bisogno di una funzione per caricare i file di traduzione nel browser a runtime. Crea un file [`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 {};
  }
}
```

Questa funzione carica i file di traduzione JSON dalla directory `src/_gt/`. La CLI genera questi file quando esegui il comando [`npx gt translate`](/docs/cli/reference/commands/translate).

<Callout type="info">
  **Rollup:** Rollup standard non è in grado di analizzare l&#39;importazione completamente dinamica sopra. Usa invece la [mappa statica del loader per le impostazioni regionali](/docs/react/guides/developing-spa-translations#setup).
</Callout>

<Accordions>
  <Accordion title="Vuoi mantenere le traduzioni di Create React App in public?">
    Create React App può usare il loader della directory sorgente riportato sopra. Se preferisci mantenere le traduzioni generate in `public/`, modifica l&#39;output della CLI in `public/_gt/[locale].json`:

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

    Carica il file tramite 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. Inizializza la libreria

Chiama **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** una volta all&#39;avvio, prima del rendering dell&#39;app. Accetta la configurazione e il loader delle traduzioni, determina l&#39;impostazione regionale dell&#39;utente e carica le traduzioni corrispondenti.

Il pattern più affidabile è un piccolo modulo di ingresso che inizializza prima GT e poi carica il resto dell&#39;app. In questo modo puoi tradurre i contenuti a livello di modulo.

```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'); // renderizza l'app solo dopo che GT è pronto
```

<Accordions>
  <Accordion title="Usi CommonJS?">
    CommonJS non supporta `await` al livello superiore. Racchiudi l&#39;inizializzazione in una funzione di avvio asincrona e importa dinamicamente l&#39;applicazione in un secondo momento. In questo modo viene mantenuto il confine asincrono richiesto per le chiamate [`t()`](/docs/react/reference/functions/t-function) a livello di modulo.

    ```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">
      **Avvertenza:** Non eseguire `require` di `main` prima dell&#39;inizializzazione. Farlo valuta le chiamate [`t()`](/docs/react/reference/functions/t-function) a livello di modulo prima che le traduzioni siano pronte.
    </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>
);
```

Quindi aggiorna il tag script del modulo nel tuo `index.html` affinché punti al nuovo punto di ingresso: cambia `src` da `/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) viene eseguito una sola volta all&#39;avvio — la configurazione rimane immutabile per tutta la durata dell&#39;app. Una volta terminata l&#39;inizializzazione, le traduzioni possono essere risolte in qualsiasi modulo. **Non è necessario avvolgere l&#39;app in un provider.**

<Accordions>
  <Accordion title="Usi Create React App?">
    Create React App blocca le importazioni dall&#39;esterno di `src/` e non abilita `await` al livello superiore. Mantieni il file `gt.config.json` nella radice per la CLI, rinomina il punto di ingresso `src/index.tsx` esistente in `src/main.tsx`, quindi crea questo nuovo punto di ingresso:

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

    Mantieni questi valori delle impostazioni regionali sincronizzati con la configurazione nella radice ogni volta che aggiungi o rimuovi una lingua. Lascia invariato `public/index.html`; Create React App carica già `src/index`.
  </Accordion>
</Accordions>

<Callout type="info">
  **Suggerimento:** Segui [Sviluppare con le traduzioni per SPA](/docs/react/guides/developing-spa-translations) per aggiungere il compilatore e le credenziali di sviluppo.
</Callout>

### 5. Contrassegna il contenuto da tradurre

Ora racchiudi il testo che vuoi tradurre con il componente **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) sta per &quot;translate&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>
  );
}
```

Puoi racchiudere dentro [`<T>`](/docs/react/reference/components/t) tutto il JSX che vuoi. Tutto ciò che contiene — testo, elementi annidati, persino la formattazione — viene tradotto come un&#39;unica unità.

Per le stringhe al di fuori dei componenti React, usa **[`t()`](/docs/react/reference/functions/t-function)**. Funziona a livello di modulo perché [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) carica le traduzioni prima del resto dell&#39;app:

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

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

### 6. Aggiungi un selettore di lingua

Inserisci un **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** per consentire agli utenti di cambiare lingua:

```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) visualizza un menu a discesa con le lingue definite nel tuo `gt.config.json`.

Quando l&#39;utente seleziona una lingua, `gt-react` salva la scelta nel cookie `generaltranslation.locale` e ricarica la pagina; [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) viene quindi eseguito di nuovo e carica le traduzioni della nuova impostazione regionale prima che venga visualizzata l&#39;app.

### 7. Autenticati e traduci

Prima di tradurre, autenticati su General Translation:

```bash
npx gt auth
```

Segui le istruzioni per creare un account o accedere. Quando ti viene richiesto il tipo di chiave, scegli una chiave di produzione. Il comando genera una chiave API e un ID progetto, quindi li aggiunge a `.env.local` nella radice del progetto:

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

<Callout type="warn">
  **Avviso:** Non includere `.env.local` nei commit e non esporre `GT_API_KEY` nel codice del browser.
</Callout>

Quindi esegui il comando `translate` per generare i file di traduzione per ogni impostazione regionale configurata:

```bash
npx gt translate
```

La CLI analizza la tua app, ne traduce i contenuti e scrive i risultati nel percorso di output specificato in `gt.config.json`. Eseguila di nuovo ogni volta che i contenuti sorgente cambiano.

### 8. Esegui e verifica

Renderizza il component di esempio dalla tua applicazione:

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

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

Avvia il server di development della tua applicazione (ad esempio, `npm run dev` con Vite), apri l&#39;URL locale e seleziona `es`, `fr` o `ja`. Verifica che la pagina si ricarichi e che il titolo mostri la traduzione selezionata.

## Risoluzione dei problemi [#troubleshooting]

<Accordions>
  <Accordion title="La lingua non cambia quando uso il menu a discesa">
    Verifica che i cookie del browser siano abilitati, che l&#39;impostazione regionale selezionata sia presente in `gt.config.json` e che [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) sia completata prima del caricamento del modulo di ingresso dell&#39;applicazione.
  </Accordion>

  <Accordion title="Alcune traduzioni non sono corrette">
    Un testo ambiguo può portare a traduzioni imprecise. Per esempio, &quot;apple&quot; potrebbe riferirsi al frutto o all&#39;azienda. Aggiungi una prop `$context` per fornire più contesto:

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

    Sia [`<T>`](/docs/react/reference/components/t) sia [`useGT()`](/docs/react/reference/hooks/use-gt) supportano l&#39;opzione `$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.