# 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
---
title: React SPA Quickstart
description: Aggiungi più lingue a un'app React a pagina singola con General Translation in meno di 10 minuti.
related:
links:
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations
---
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+
**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.
**Nota:** Se la tua app esegue il rendering sul server, segui invece la [React Quickstart](/docs/react/react-quickstart).
## 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.
```bash
npm i gt-react
npm i -D gt
```
```bash
yarn add gt-react
yarn add --dev gt
```
```bash
bun add gt-react
bun add --dev gt
```
```bash
pnpm add gt-react
pnpm add --save-dev gt
```
### 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'[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).
**Nota:** I bundler come Vite importano i file di traduzione come moduli, quindi i file di traduzione devono trovarsi all'interno di `src/`.
### 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).
### 4. Inizializza la libreria
Chiama **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** una volta all'avvio, prima del rendering dell'app. Accetta la configurazione e il loader delle traduzioni, determina l'impostazione regionale dell'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'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
```
CommonJS non supporta `await` al livello superiore. Racchiudi l'inizializzazione in una funzione di avvio asincrona e importa dinamicamente l'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);
```
**Avvertenza:** Non eseguire `require` di `main` prima dell'inizializzazione. Farlo valuta le chiamate [`t()`](/docs/react/reference/functions/t-function) a livello di modulo prima che le traduzioni siano pronte.
```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')!).render(
);
```
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"
```
[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) viene eseguito una sola volta all'avvio — la configurazione rimane immutabile per tutta la durata dell'app. Una volta terminata l'inizializzazione, le traduzioni possono essere risolte in qualsiasi modulo. **Non è necessario avvolgere l'app in un provider.**
**Suggerimento:** Segui [Sviluppare con le traduzioni per SPA](/docs/react/guides/developing-spa-translations) per aggiungere il compilatore e le credenziali di sviluppo.
### 5. Contrassegna il contenuto da tradurre
Ora racchiudi il testo che vuoi tradurre con il componente **[``](/docs/react/reference/components/t)**. [``](/docs/react/reference/components/t) sta per "translate":
```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';
export default function Welcome() {
return (
Welcome to my app
This content will be translated automatically.
);
}
```
Puoi racchiudere dentro [``](/docs/react/reference/components/t) tutto il JSX che vuoi. Tutto ciò che contiene — testo, elementi annidati, persino la formattazione — viene tradotto come un'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'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 **[``](/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 (