# General Translation React SDKs (gt-react, gt-next, gt-react-native): Quickstart di TanStack Start
URL: https://generaltranslation.com/it/docs/react/tanstack-start-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Aggiungi General Translation a un'app TanStack Start con gt-tanstack-start e traduci i tuoi primi contenuti.

`gt-tanstack-start` aggiunge l'internazionalizzazione automatica alle app TanStack Start. Inizializzi General Translation nel punto di ingresso del router, risolvi l'impostazione regionale della richiesta e idrati [`GTProvider`](/docs/react/reference/components/gt-provider) da un loader della route.

Usa questo quickstart per le app TanStack Start. Per una normale React SPA, usa il [React Quickstart](/docs/react/react-quickstart).

<Callout type="warn">
  **Avviso:** `gt-tanstack-start` è sperimentale e potrebbe introdurre modifiche incompatibili. Non è ancora consigliato per l&#39;uso in produzione.
</Callout>

## Quickstart [#quickstart]

Installa i pacchetti, crea un file di configurazione e un loader delle traduzioni, aggiungi il middleware per le richieste, inizializza il router, configura la route principale, contrassegna i contenuti da tradurre e genera le traduzioni.

### 1. Installa `gt-tanstack-start`

Installa `gt-tanstack-start` e `gt-react` come dipendenze e la [CLI `gt`](/docs/cli/quickstart) come dipendenza di sviluppo. `gt-react` è richiesto direttamente affinché la CLI possa rilevare i componenti [`<T>`](/docs/react/reference/components/t) nel codice sorgente.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-tanstack-start gt-react && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-tanstack-start gt-react && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-tanstack-start gt-react && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-tanstack-start gt-react && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

`gt-tanstack-start` supporta solo ESM. Usa la sintassi `import` anziché `require()` di CommonJS.

*Nota: questa configurazione richiede `gt-tanstack-start` 11.1.5 o versione successiva affinché [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) venga risolto dall&#39;entry principale del pacchetto nelle build client.*

### 2. Crea `gt.config.json`

Crea un file `gt.config.json` nella radice del progetto. Definisce la lingua sorgente, le impostazioni regionali di destinazione e il percorso in cui vengono scritti i file di traduzione.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "files": {
    "gt": {
      "output": "src/_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` — dove la CLI scrive i file di traduzione. Tienili in `src/` così Vite può importarli; i file in `public/` non verranno risolti.

### 3. Crea un loader delle traduzioni

Crea un file `loadTranslations.ts` che importi, a runtime, il file di traduzione di un&#39;impostazione regionale.

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

### 4. Aggiungi il middleware per le richieste

Crea `src/start.ts` e registra [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) come middleware globale per le richieste. Mantieni il middleware CSRF di TanStack Start quando definisci un&#39;istanza Start personalizzata.

```ts title="src/start.ts"
import { createCsrfMiddleware, createStart } from '@tanstack/react-start';
import { gtMiddleware } from 'gt-tanstack-start';

const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware, gtMiddleware],
}));
```

Il middleware associa a ogni richiesta l&#39;impostazione regionale, la regione e la configurazione di internazionalizzazione, così che le funzioni server utilizzino la lingua corretta. Completa l&#39;inizializzazione nel passaggio successivo prima di avviare il server di sviluppo.

### 5. Inizializza General Translation e configura la route principale

Chiama [`initializeGT`](/docs/react/tanstack-start/setup#initialize) una sola volta a livello di modulo in `src/router.tsx`. Aggiungi gli import e l&#39;inizializzatore al file del router esistente:

```tsx title="src/router.tsx"
import { initializeGT } from 'gt-tanstack-start';
import gtConfig from '../gt.config.json';
import loadTranslations from '../loadTranslations';

initializeGT({ ...gtConfig, loadTranslations });
```

Quindi risolvi l&#39;impostazione regionale con [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) e carica uno snapshot delle traduzioni nel loader di `src/routes/__root.tsx`. Passa `locale` e `translations` a [`GTProvider`](/docs/react/reference/components/gt-provider).

```tsx title="src/routes/__root.tsx"
import {
  HeadContent,
  Scripts,
  createRootRoute,
} from '@tanstack/react-router';
import {
  GTProvider,
  getLocale,
  getTranslationsSnapshot,
  LocaleSelector,
} from 'gt-tanstack-start';

export const Route = createRootRoute({
  loader: async () => {
    const locale = getLocale();
    return {
      locale,
      translations: await getTranslationsSnapshot(locale),
    };
  },
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  const { locale, translations } = Route.useLoaderData();
  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <GTProvider locale={locale} translations={translations}>
          <LocaleSelector />
          {children}
        </GTProvider>
        <Scripts />
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) legge l&#39;impostazione regionale con ambito richiesta sul server e l&#39;impostazione regionale del browser inizializzata sul client. [`GTProvider`](/docs/react/reference/components/gt-provider) richiede sia `locale` sia `translations`.

<Callout type="warn">
  **Avviso:** Questi file di traduzione (`src/_gt/[locale].json`) non esistono finché non li crei. L&#39;impostazione regionale predefinita viene comunque renderizzata, ma selezionare un&#39;impostazione regionale di destinazione nel language switcher restituisce un HTTP 500 finché i file non esistono. Esegui prima [`npx gt generate`](/docs/cli/reference/commands/generate) (non serve alcuna chiave API) oppure [`npx gt translate`](/docs/cli/reference/commands/translate) (con le credenziali) per crearli.
</Callout>

### 6. Contrassegna il contenuto per la traduzione

Racchiudi il JSX nel componente [`<T>`](/docs/react/reference/components/t) per tradurlo in-place. Importa [`<T>`](/docs/react/reference/components/t) e [`useGT`](/docs/react/reference/hooks/use-gt) da `gt-react` in modo che la CLI li rilevi durante la scansione del codice sorgente.

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { T, useGT } from 'gt-react';

export const Route = createFileRoute('/')({ component: Home });

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

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

[`useGT()`](/docs/react/reference/hooks/use-gt) restituisce direttamente la funzione di traduzione, quindi usala così: `const gt = useGT();`.

### 7. Genera le traduzioni

Esegui la CLI per tradurre il tuo progetto usando l&#39;API di General Translation.

```bash
npx gt translate
```

Aggiungi il comando allo script di build, in modo che le build di produzione abbiano sempre traduzioni aggiornate:

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

<Callout type="info">
  **Nota:** [`npx gt translate`](/docs/cli/reference/commands/translate) richiede un ID progetto e una chiave API di produzione, da impostare come `GT_PROJECT_ID` e `GT_API_KEY` nel tuo ambiente. Esegui [`npx gt auth`](/docs/cli/reference/commands/auth) o visita la [Dashboard](/docs/platform/dashboard/get-started) per ottenerli.
</Callout>

## 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.