# General Translation React SDKs (gt-react, gt-next, gt-react-native): Avvio rapido per React Router
URL: https://generaltranslation.com/it/docs/react/react-router-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Aggiungi General Translation a un'app React Router in modalità framework, inclusi gli storefront Shopify Hydrogen, e traduci i tuoi primi contenuti.

`gt-react` funziona con React Router in modalità framework tramite la route principale. Inizializzi la libreria in `app/root.tsx`, risolvi l'impostazione regionale di ogni visitatore nel loader radice e renderizzi [`GTProvider`](/docs/react/reference/components/gt-provider) dal `Layout` radice.

Usa questo avvio rapido per le app create con `@react-router/dev`. Se usi React Router come libreria all'interno di una single-page app Vite, segui invece la [Guida rapida per SPA React](/docs/react/react-spa-quickstart).

Esegui [`npx gt@latest init`](/docs/cli/reference/commands/init) dalla radice dell'app per automatizzare la configurazione. La procedura guidata installa `gt-react`, crea il config e il loader delle traduzioni e configura un file `app/root.tsx` generato dallo starter create-react-router o Hydrogen. Gli altri file root restano invariati e vengono elencate le eventuali operazioni da eseguire manualmente; questa guida illustra la stessa configurazione passo per passo, a mano.

*Nota: questa configurazione richiede `gt-react` 11.1.3 o versioni successive e un'app che esegua il rendering a ogni richiesta. La modalità SPA (`ssr: false`), il pre-rendering e la RSC Framework Mode non sono supportati.*

## Avvio rapido [#quickstart]

### 1. Installa i pacchetti

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

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-react && npm install gt --save-dev
    ```
  </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 `gt.config.json`

Crea un file `gt.config.json` nella radice del progetto. Il file specifica la lingua di origine, le impostazioni locali di destinazione e la posizione in cui vengono scritti i file di traduzione.

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

* `defaultLocale` — la lingua in cui è scritta la tua app.
* `locales` — le lingue in cui tradurre. Scegli tra le [impostazioni regionali supportate](/docs/platform/dashboard/reference/supported-locales).
* `files.gt.output` — il percorso in cui la CLI scrive i file di traduzione. Tienili all&#39;interno di `app/`, così Vite li include nei bundle insieme al codice server e client.

### 3. Crea un loader delle traduzioni

Crea `app/loadTranslations.ts`. Questo file importa il file di traduzione di un&#39;impostazione regionale quando il loader radice lo richiede.

```ts title="app/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

Quindi crea un file `{}` vuoto per ogni impostazione regionale di destinazione, ad esempio `app/_gt/es.json` e `app/_gt/ja.json`; [`gt init`](/docs/cli/reference/commands/init) li crea automaticamente. Un&#39;impostazione regionale priva di file di traduzione viene renderizzata nella lingua predefinita.

### 4. Configura la route principale

Chiama [`initializeGT`](/docs/react/reference/config#initialize) una sola volta a livello di modulo in `app/root.tsx`, restituisci l&#39;impostazione regionale e un&#39;istantanea delle traduzioni dal loader radice e racchiudi il contenuto di `Layout` in [`GTProvider`](/docs/react/reference/components/gt-provider). Aggiungi le righe evidenziate al tuo file root esistente:

```tsx title="app/root.tsx"
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useRouteLoaderData, // [!code ++]
} from 'react-router';
import { GTProvider, getTranslationsSnapshot, initializeGT, parseLocale } from 'gt-react'; // [!code ++]

import type { Route } from './+types/root';
import gtConfig from '../gt.config.json'; // [!code ++]
import loadTranslations from './loadTranslations'; // [!code ++]
import './app.css';

initializeGT({ ...gtConfig, loadTranslations }); // [!code ++]

// [!code ++:11]
// Le pagine di errore non hanno dati del loader. In questi casi GTProvider viene omesso, così non
// sostituisce l'impostazione regionale salvata dal visitatore con quella predefinita.
function RootGTProvider({ children }: { children: React.ReactNode }) {
  const data = useRouteLoaderData<typeof loader>('root');
  if (!data) return <>{children}</>;
  return (
    <GTProvider locale={data.locale} translations={data.translations}>
      {children}
    </GTProvider>
  );
}

// [!code ++:4]
export async function loader({ request }: Route.LoaderArgs) {
  const locale = parseLocale(request);
  return { locale, translations: await getTranslationsSnapshot(locale) };
}

export function Layout({ children }: { children: React.ReactNode }) {
  const locale = useRouteLoaderData<typeof loader>('root')?.locale ?? gtConfig.defaultLocale; // [!code ++]
  return (
    // [!code ++]
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {/* [!code ++] */}
        <RootGTProvider>
          {children}
          <ScrollRestoration />
        {/* [!code ++] */}
        </RootGTProvider>
        <Scripts />
      </body>
    </html>
  );
}

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

`parseLocale` legge il cookie dell&#39;impostazione regionale, poi l&#39;intestazione `Accept-Language`, e in mancanza di entrambi ricorre a `defaultLocale` come valore alternativo. Se la tua route radice ha già un `loader`, aggiungi `locale` e `translations` all&#39;oggetto che restituisce.

*Nota: le pagine di errore senza i dati del loader radice, come un 404 diretto o un errore del loader radice, vengono renderizzate senza [`GTProvider`](/docs/react/reference/components/gt-provider). In questi casi, i componenti di traduzione e gli hooks, come [`<T>`](/docs/react/reference/components/t) e [`useLocale`](/docs/react/reference/hooks/use-locale), sollevano un&#39;eccezione e trasformano la pagina di errore in un errore del server: per questo motivo, non tradurre l&#39;`ErrorBoundary` radice.*

### 5. Contrassegna il contenuto da tradurre

Racchiudi il JSX nel componente [`<T>`](/docs/react/reference/components/t) per tradurlo in-place e usa [`useGT`](/docs/react/reference/hooks/use-gt) per le semplici stringhe, come i valori di `aria-label`. Aggiungi un [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) per permettere ai visitatori di cambiare lingua.

```tsx title="app/routes/home.tsx"
import { LocaleSelector, T, useGT } from 'gt-react';

export default function Home() {
  const gt = useGT();

  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email address')} />
    </main>
  );
}
```

Quando un visitatore sceglie una lingua, [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) la salva nel cookie dell&#39;impostazione regionale e ricarica la pagina, così il loader radice renderizza la nuova impostazione regionale.

### 6. Genera traduzioni

Accedi con [`gt login`](/docs/cli/reference/commands/login), imposta il [`projectId`](/docs/cli/reference/config#project-id) del tuo progetto esistente in `gt.config.json` oppure la variabile d&#39;ambiente `GT_PROJECT_ID`, quindi avvia la traduzione:

```bash
npx gt login
GT_PROJECT_ID=your-project-id npx gt translate
```

L&#39;accesso non seleziona automaticamente un progetto. Se non ne hai uno, crealo nella [Dashboard](/docs/platform/dashboard/get-started) oppure esegui [`gt init`](/docs/cli/reference/commands/init) e attiva le traduzioni in tempo reale durante lo sviluppo per sceglierne o crearne uno.

Avvia il server di sviluppo e cambia lingua per vedere le traduzioni. Anteponi il comando al tuo script di build esistente, così le build di produzione includeranno sempre le traduzioni aggiornate:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && react-router build"
  }
}
```

Per caricare le traduzioni dalla CDN invece di includerle nel bundle, esegui [`npx gt configure --storage cdn`](/docs/cli/reference/commands/configure). Il comando indica la modifica da apportare in `app/root.tsx`.

Se memorizzi nella cache le risposte dei documenti, ad esempio su una CDN o su un reverse proxy, differenzia la cache in base all&#39;impostazione regionale, così che i visitatori non ricevano la pagina in un&#39;altra lingua. Invia `Vary: Cookie, Accept-Language` nelle risposte dei documenti, oppure escludile dalle cache condivise.

<Callout type="info">
  **Nota:** per la CI, fornisci una `GT_API_KEY` separata con ambito limitato e lo stesso ID progetto tramite le impostazioni dei segreti. (Vedi [Credenziali della CLI](/docs/cli/guides/configuring#credentials)).
</Callout>

## Shopify Hydrogen [#hydrogen]

Gli storefront Hydrogen sono app basate sul framework React Router e seguono gli stessi passaggi. Mantieni il comando di build di Hydrogen e anteponigli la generazione delle traduzioni:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && shopify hydrogen build --codegen"
  }
}
```

`gt-react` traduce il testo presente nel codice del tuo storefront, come la navigazione, i pulsanti e i testi delle pagine. I titoli e le descrizioni dei prodotti e gli altri contenuti del negozio provengono invece da Shopify: traducili direttamente lì.

## Risoluzione dei problemi [#troubleshooting]

<Accordions>
  <Accordion title="gt init ha lasciato invariato app/root.tsx">
    La procedura guidata modifica solo i file root con una struttura analoga a quella degli starter di create-react-router o Hydrogen e che non chiamano già [`initializeGT`](/docs/react/reference/config#initialize). Segui il [passaggio 4](#quickstart) per apportare le modifiche manualmente.
  </Accordion>

  <Accordion title="gt init si è interrotto prima di apportare modifiche">
    La soluzione dipende dal motivo:

    * **Modalità SPA, pre-rendering o RSC Framework Mode:** questa configurazione legge l&#39;impostazione regionale di ogni visitatore in un loader radice a ogni richiesta, quindi queste modalità non sono supportate, né tramite la procedura guidata né con la configurazione manuale.
    * **Un intervallo di versioni di `gt-react` che include versioni precedenti alla 11.1.3:** aggiorna `gt-react` ed esegui di nuovo `npx gt@latest init`.
    * **Un `appDirectory` diverso da `app` o un `react-router.config` che la procedura guidata non riesce a leggere:** se l&#39;app esegue il rendering a ogni richiesta, esegui `npx gt@latest init --no-react-setup` per configurare tutto tranne il codice sorgente, quindi segui i passaggi da 2 a 4 sostituendo `app/` con la directory dell&#39;app, anche in `files.gt.output`.
  </Accordion>

  <Accordion title="La lingua non cambia quando uso il selettore">
    Verifica che i cookie siano abilitati, che l&#39;impostazione regionale sia presente in `gt.config.json` e che il selettore venga renderizzato all&#39;interno di `RootGTProvider`. Se `<html lang>` cambia ma il testo no, esegui [`npx gt translate`](/docs/cli/reference/commands/translate) per popolare `app/_gt/[locale].json`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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