# General Translation React SDKs (gt-react, gt-next): React Quickstart
URL: https://generaltranslation.com/it/docs/react/react-quickstart.mdx
---
title: React Quickstart
description: Aggiungi più lingue a un'app React con rendering lato server con General Translation in meno di 10 minuti.
related:
links:
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
---
# React Quickstart
Al termine di questa guida, la tua app React con rendering lato server mostrerà contenuti in più lingue, con un selettore di lingua con cui i tuoi utenti potranno interagire.
**Prerequisiti:**
* Un'app React con rendering lato server (React Router o una configurazione SSR personalizzata)
* Node.js 18+
**Nota:** Se la tua app viene renderizzata interamente nel browser con Vite, segui invece [React SPA Quickstart](/docs/react/react-spa-quickstart). In quel caso, il provider viene completamente omesso.
## Quickstart [#quickstart]
### 1. Installa i pacchetti
`gt-react` è la libreria che gestisce le traduzioni nella tua app. `gt` è lo strumento CLI che prepara le traduzioni per l'ambiente di produzione.
```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 per la 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 import nella funzione `loadTranslations` (Passaggio 3).
### 3. Crea un loader delle traduzioni
Crea una funzione `loadTranslations` che carica il file di traduzione di un'impostazione regionale. Sul server viene eseguita durante la renderizzazione; la CLI genera i file quando esegui `npx gt translate`:
```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) {
return {};
}
}
```
### 4. Inizializza la libreria
Chiama **`initializeGT`** a livello di modulo in un file che viene caricato sia sul server sia sul client — la route radice o il layout sono i punti più naturali in cui farlo. Registra la configurazione e il loader delle traduzioni una sola volta; la configurazione è immutabile per tutta la durata dell'app:
```tsx title="src/routes/root.tsx"
import { initializeGT } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from '../loadTranslations';
initializeGT({
defaultLocale: gtConfig.defaultLocale,
locales: gtConfig.locales,
loadTranslations,
});
```
### 5. Carica le traduzioni sul server
Nel loader della route radice (o in un handler server equivalente), individua l'impostazione regionale della richiesta e recupera uno snapshot delle traduzioni con **`getTranslationsSnapshot`**, quindi passali entrambi a **``**:
```tsx title="src/routes/root.tsx"
import {
GTProvider,
getTranslationsSnapshot,
parseLocale,
} from 'gt-react';
// Nel loader della tua route (l'API esatta dipende dal framework)
export async function loader({ request }) {
const locale = parseLocale(request); // [!code highlight]
return {
locale,
translations: await getTranslationsSnapshot(locale), // [!code highlight]
};
}
export default function Root({ children }) {
const { locale, translations } = useLoaderData();
return (
{children}
);
}
```
### 6. Contrassegna il contenuto da tradurre
Racchiudi con il componente **``** qualsiasi testo che vuoi tradurre. `` 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.
);
}
```
Per stringhe semplici — come gli attributi `placeholder` o i valori `aria-label` — usa l'hook **`useGT`**:
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Aggiungi un selettore di lingua
Inserisci un **``** così gli utenti possono cambiare lingua:
```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';
export default function Header() {
return ;
}
```
Quando l'utente seleziona una lingua, `gt-react` memorizza la scelta nel cookie `generaltranslation.locale` e ricarica la pagina, così il server renderizza nuovamente tutto nella nuova impostazione regionale.
### 8. Configura le variabili d'ambiente (opzionale)
Le traduzioni di sviluppo on-demand vengono eseguite nel browser. Rendi disponibili al codice client l'ID progetto e la chiave API di sviluppo usando le variabili d'ambiente pubbliche del tuo framework. Non esporre mai una chiave API di produzione.
Con Vite, `gt-react` legge automaticamente queste variabili:
```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```
Per gli altri framework, usa la convenzione prevista per le variabili d'ambiente lato client e passa i valori esposti a `initializeGT`.
Ottieni gratuitamente le tue chiavi su [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) oppure eseguendo:
```bash
npx gt auth
```
**Attenzione:** Per lo sviluppo, usa una chiave che inizia con `gtx-dev-`. Le chiavi di produzione (`gtx-api-`) sono solo per CI/CD.
### 9. Distribuisci in produzione
In produzione, le traduzioni vengono generate in anticipo in fase di build (senza chiamate API in tempo reale). Aggiungi il comando translate al tuo script di build:
```json title="package.json"
{
"scripts": {
"build": "npx gt translate && "
}
}
```
Imposta le variabili d'ambiente di **produzione** sul tuo provider di hosting:
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
**Avviso:** Le chiavi di Production iniziano con `gtx-api-` (non `gtx-dev-`). Puoi ottenerne una da [dash.generaltranslation.com](https://dash.generaltranslation.com). Non esporre mai pubblicamente la tua `GT_API_KEY`.
Ecco fatto: la tua app ora è multilingue. 🎉
## Risoluzione dei problemi [#troubleshooting]
`gt-react` memorizza la preferenza della lingua dell'utente in un cookie chiamato `generaltranslation.locale`. Se in precedenza hai eseguito dei test con una lingua diversa, questo cookie potrebbe sovrascrivere la tua selezione. Cancella i cookie e riprova.
* [Chrome](https://support.google.com/chrome/answer/95647)
* [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
* [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
È normale. In sviluppo, le traduzioni avvengono on-demand (i contenuti vengono tradotti in tempo reale tramite l'API). Questo ritardo **non si verifica in produzione**: tutte le traduzioni vengono pre-generate da `npx gt translate`.
Un testo ambiguo può portare a traduzioni imprecise. Per esempio, "apple" può indicare il frutto oppure l'azienda. Per maggiore chiarezza, aggiungi una prop `$context`:
```jsx
Apple
```
Sia `` che `useGT()` supportano l'opzione `$context`.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables