# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configura TanStack Start
URL: https://generaltranslation.com/it/docs/react/tanstack-start/setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Registra il middleware per le richieste di General Translation, inizializza un'app TanStack Start, determina l'impostazione regionale e idrata il provider.

`gt-tanstack-start` usa un middleware globale per le richieste, l&#39;inizializzazione del router a livello di modulo e un loader della route root. Il middleware crea uno stato locale per la richiesta per il codice server, mentre il loader root idrata [`<GTProvider>`](/docs/react/reference/components/gt-provider) con l&#39;impostazione regionale e le traduzioni.

Questa pagina copre la configurazione specifica di TanStack Start. Per la procedura completa, inclusi l&#39;installazione e la CLI, segui il [Quickstart di TanStack Start](/docs/react/tanstack-start-quickstart).

<Callout type="warn">
  **Avvertenza:** `gt-tanstack-start` è sperimentale e potrebbe introdurre modifiche incompatibili.
</Callout>

*Nota: `gt-tanstack-start` supporta solo ESM. Usa la sintassi `import` invece di CommonJS `require()`.*

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

## Carica le traduzioni [#load-translations]

Crea una funzione [`loadTranslations`](/docs/react/reference/functions/load-translations) che importi il file di traduzione per un&#39;impostazione regionale. Tieni i file in `src/` in modo che Vite possa importarli.

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

La CLI genera questi file quando esegui [`npx gt translate`](/docs/cli/reference/commands/translate).

## Registra il middleware per le richieste [#middleware]

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

```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 determina l&#39;impostazione regionale, la regione e l&#39;impostazione di internazionalizzazione una volta per ogni richiesta. Mantiene l&#39;impostazione regionale determinata nel cookie dell&#39;impostazione regionale e rende disponibile lo stato della richiesta alle [funzioni runtime isomorfe](/docs/react/tanstack-start/using-server-functions) sul server.

## Inizializza e determina l&#39;impostazione regionale [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize), [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) e [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) vengono importati da `gt-tanstack-start`:

* **[`initializeGT`](/docs/react/reference/config#initialize)** — chiamalo una sola volta a livello di modulo in `src/router.tsx`. Usa lo spread di `gt.config.json` e passa [`loadTranslations`](/docs/react/reference/functions/load-translations).
* **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — restituisce l&#39;impostazione regionale dall&#39;ambito middleware attivo sul server e dallo store di condizioni del browser inizializzato sul client.
* **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — carica le traduzioni di un&#39;impostazione regionale nel formato previsto da [`<GTProvider>`](/docs/react/reference/components/gt-provider), così il contenuto viene visualizzato senza effetti flash durante il caricamento. Consulta il [riferimento](/docs/react/reference/functions/get-translations-snapshot).

## Abilita il routing delle impostazioni regionali [#locale-routing]

Il routing delle impostazioni regionali è opt-in. Prima di abilitarlo, configura TanStack Router affinché corrisponda sia all&#39;URL dell&#39;impostazione regionale predefinita senza prefisso, ad esempio `/about`, sia agli URL con prefisso dell&#39;impostazione regionale, ad esempio `/es/about`.

Puoi aggiungere un [segmento facoltativo `/{-$locale}`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters) alle tue route basate su file o su codice, oppure usare l&#39;[opzione `rewrite` di TanStack Router](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite) per mappare gli URL pubblici con prefisso dell&#39;impostazione regionale al tuo albero delle route esistente. Ad esempio, il percorso facoltativo della route `/{-$locale}/about` corrisponde a `/about`, `/es/about` e `/ja/about`.

Dopo che il router accetta entrambe le forme di URL, imposta `localeRouting` su `true` in `gt.config.json`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "localeRouting": true
}
```

`gt-tanstack-start` non crea né ristruttura le route dell&#39;applicazione. L&#39;opzione fa sì che determini l&#39;impostazione regionale da un prefisso di percorso supportato e aggiorni il pathname quando l&#39;impostazione regionale cambia. L&#39;impostazione regionale predefinita rimane senza prefisso, ad esempio `/about`, mentre le altre impostazioni regionali usano un prefisso, ad esempio `/es/about`.

Sul server, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) determina l&#39;impostazione regionale dal percorso, poi dal cookie dell&#39;impostazione regionale, dall&#39;header `Accept-Language` e da `defaultLocale`. Sul client, le modifiche dell&#39;impostazione regionale ricaricano il pathname corrispondente e ne preservano la query string e l&#39;hash.

Il percorso di base di TanStack Router viene rispettato tramite `TSS_ROUTER_BASEPATH`.

## Inizializza il router e configura la route root [#root-route]

Aggiungi le importazioni e l&#39;inizializzatore di [`initializeGT`](/docs/react/reference/config#initialize) al file `src/router.tsx` 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 determina l&#39;impostazione regionale e carica lo snapshot nel loader `src/routes/__root.tsx`. Passa `locale` e `translations` a [`<GTProvider>`](/docs/react/reference/components/gt-provider) nel componente shell.

```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>
  );
}
```

[`<GTProvider>`](/docs/react/reference/components/gt-provider) qui richiede sia `locale` sia `translations`, a differenza di Next.js, dove è il server a risolverli, o di React Native, dove il provider li carica autonomamente.

[`initializeGT`](/docs/react/reference/config#initialize) deve essere eseguito prima che [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) gestisca una richiesta. Completa la configurazione del router e della route root prima di avviare il server di sviluppo.

## Contrassegna il contenuto per la traduzione [#content]

Nei componenti della route, avvolgi il JSX in [`<T>`](/docs/react/reference/components/t) e traduci le stringhe con [`useGT`](/docs/react/reference/hooks/use-gt). Importali 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>
  );
}
```

## Sitemap

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