# General Translation React SDKs (gt-react, gt-next, gt-react-native): React Quickstart
URL: https://generaltranslation.com/it/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Aggiungi più lingue a un'app React con rendering lato server con General Translation in meno di 10 minuti.

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+

<Callout type="info">
  **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.
</Callout>

## 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&#39;ambiente di produzione.

<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 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&#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 import nella funzione [`loadTranslations`](/docs/react/reference/functions/load-translations) (Passaggio 3).

### 3. Crea un loader delle traduzioni

Crea una funzione [`loadTranslations`](/docs/react/reference/functions/load-translations) che carica il file di traduzione di un&#39;impostazione regionale. Sul server viene eseguita durante la renderizzazione; la CLI genera i file quando esegui [`npx gt translate`](/docs/cli/reference/commands/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`](/docs/react/reference/config#initialize)** 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&#39;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&#39;impostazione regionale della richiesta e recupera uno snapshot delle traduzioni con **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)**, quindi passali entrambi a **[`<GTProvider>`](/docs/react/reference/components/gt-provider)**:

```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 (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

### 6. Contrassegna il contenuto da tradurre

Racchiudi con il componente **[`<T>`](/docs/react/reference/components/t)** qualsiasi testo che vuoi tradurre. [`<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>
  );
}
```

Per stringhe semplici — come gli attributi `placeholder` o i valori `aria-label` — usa l&#39;hook **[`useGT`](/docs/react/reference/hooks/use-gt)**:

```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```

### 7. Aggiungi un selettore di lingua

Inserisci un **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** così gli utenti possono cambiare lingua:

```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';

export default function Header() {
  return <LocaleSelector />;
}
```

Quando l&#39;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&#39;ambiente (opzionale)

Le traduzioni di sviluppo on-demand vengono eseguite nel browser. Rendi disponibili al codice client l&#39;ID progetto e la chiave API di sviluppo usando le variabili d&#39;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&#39;ambiente lato client e passa i valori esposti a [`initializeGT`](/docs/react/reference/config#initialize).

Ottieni gratuitamente le tue chiavi su [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) oppure eseguendo:

```bash
npx gt auth
```

<Callout type="warn">
  **Attenzione:** Per lo sviluppo, usa una chiave che inizia con `gtx-dev-`. Le chiavi di Production (`gtx-api-`) sono solo per CI/CD.
</Callout>

### 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 && <YOUR_BUILD_COMMAND>"
  }
}
```

Imposta le variabili d&#39;ambiente di **produzione** sul tuo provider di hosting:

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **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`.
</Callout>

Ecco fatto: la tua app ora è multilingue. 🎉

## Risoluzione dei problemi [#troubleshooting]

<Accordions>
  <Accordion title="La lingua non cambia quando uso il menu a tendina">
    Verifica che i cookie del browser siano abilitati, che l&#39;impostazione regionale selezionata sia presente in `gt.config.json` e che il selettore venga renderizzato all&#39;interno di [`<GTProvider>`](/docs/react/reference/components/gt-provider). Se fornisci una callback personalizzata [`_reload`](/docs/react/reference/components/gt-provider#reload), verifica che ricarichi la pagina o esegua la navigazione dopo la selezione.
  </Accordion>

  <Accordion title="Le traduzioni sono lente in sviluppo">
    È normale. In sviluppo, le traduzioni avvengono on-demand (i contenuti vengono tradotti in tempo reale tramite l&#39;API). Questo ritardo **non si verifica in produzione**: tutte le traduzioni vengono generate in anticipo da [`npx gt translate`](/docs/cli/reference/commands/translate).
  </Accordion>

  <Accordion title="Alcune traduzioni sono imprecise">
    Un testo ambiguo può portare a traduzioni imprecise. Per esempio, &quot;apple&quot; può indicare il frutto oppure l&#39;azienda. Per maggiore chiarezza, aggiungi una prop `$context`:

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

    Sia [`<T>`](/docs/react/reference/components/t) che [`useGT()`](/docs/react/reference/hooks/use-gt) supportano l&#39;opzione `$context`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.