# General Translation Knowledge Base: Come si aggiunge l'i18n a TanStack Start?
URL: https://generaltranslation.com/it/kb/add-i18n-to-tanstack-start.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: TanStack Start non offre un supporto i18n integrato, quindi occorre aggiungere una libreria che risolva l'impostazione regionale per ogni richiesta al server, di solito tramite un prefisso nell'URL o un cookie, e carichi i messaggi prima del rendering. Paraglide JS, react-i18next e Lingui renderizzano le traduzioni che fornisci tu; il pacchetto sperimentale gt-tanstack-start di General Translation, invece, le genera anche a partire dai testi scritti inline nel JSX.
Category: Internazionalizzazione
Last updated: 2026-10-28
Authors: General Translation Team
Published: 2026-10-28

TanStack Start non include un livello di i18n, quindi devi aggiungere tu tre elementi: una libreria che renderizzi il testo nella lingua attiva, un meccanismo per risolvere la lingua a ogni richiesta al server e le traduzioni stesse. Start renderizza l'intero documento sul server e poi lo idrata nel browser, perciò server e client devono usare la stessa impostazione regionale e gli stessi messaggi; altrimenti il primo rendering viene mostrato nella lingua sbagliata oppure l'idratazione fallisce.

## Cosa offre TanStack Start e cosa lascia a te

TanStack Start è "un framework React full-stack basato su TanStack Router", con rendering server-side (SSR) dell'intero documento, streaming, funzioni server e middleware delle richieste ([panoramica di TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview)). Diversi di questi elementi sono la base su cui poggia una configurazione i18n:

* **URL localizzati.** Un parametro di percorso facoltativo come `/{-$locale}/about` corrisponde a `/about`, `/es/about` e `/fr/about` con un unico file di route; in alternativa, l'opzione `rewrite` del router può aggiungere e rimuovere un prefisso del locale ([guida i18n di TanStack Router](https://tanstack.com/router/latest/docs/guide/internationalization-i18n)).
* **Middleware delle richieste.** Il middleware registrato con `createStart` in `src/start.ts` viene eseguito prima di ogni richiesta, incluse SSR e funzioni server ([middleware di TanStack Start](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)). È qui che una libreria i18n legge l'URL, un cookie o l'intestazione `Accept-Language`.
* **Loader e `head`.** Un loader della rotta radice può caricare i messaggi dell&#39;impostazione regionale prima del rendering, mentre l&#39;`head` di ogni route imposta il `<title>` tradotto e i meta tag.

Cosa Start lascia a te: i cataloghi dei messaggi e il runtime che li consulta, il rilevamento del locale e il cookie che ricorda la scelta dell&#39;utente, l&#39;attributo `<html lang>` nella shell radice, la formattazione dei plurali e dei numeri, i link `hreflang` e, naturalmente, le traduzioni. La guida i18n di TanStack tratta Paraglide JS in modo approfondito, inclusa una configurazione SSR per TanStack Start, e rimanda a guide della community per Intlayer e use-intl. La CLI di TanStack offre inoltre un add-on `paraglide` per le nuove app.

## Le opzioni disponibili

| Libreria                                                | Come scrivi i testi                                                                                                      | Impostazione regionale sul server                                                                                                                                                       | Da dove provengono le traduzioni                                                                       |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [Paraglide JS](https://paraglidejs.com/tanstack-start)  | Messaggi in file JSON per ogni impostazione regionale, compilati in funzioni tipizzate come `m.greeting()`               | `paraglideMiddleware` racchiude il gestore del server; le strategie includono URL, cookie e lingua preferita                                                                            | Tu, i traduttori o un comando di traduzione automatica che esegui sui file                             |
| [react-i18next](https://react.i18next.com/latest/ssr)   | Chiavi in namespace JSON, renderizzate con `t('home.title')`                                                             | La sua documentazione non prevede un&#39;integrazione con TanStack Start; devi fornire un&#39;istanza per-request e passare `initialLanguage` e `initialI18nStore` al client            | Tu, i traduttori o un sistema di gestione delle traduzioni (TMS) come Locize                           |
| [Lingui](https://lingui.dev/ref/vite-plugin)            | Macro `<Trans>` inline, estratte in cataloghi PO                                                                         | Il suo plugin Vite compila i cataloghi; sei tu ad attivare l&#39;impostazione regionale della richiesta sul server e nel browser                                                        | Tu, i traduttori o un servizio sincronizzato con i cataloghi                                           |
| General Translation (`gt-tanstack-start`, sperimentale) | JSX racchiuso in [`<T>`](/docs/react/reference/components/t), stringhe con [`useGT`](/docs/react/reference/hooks/use-gt) | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware): prefisso URL (opt-in), poi cookie, poi `Accept-Language` e infine l&#39;impostazione locale predefinita | Generate da [`npx gt translate`](/docs/cli/reference/commands/translate) e revisionate nella Dashboard |

Scegli Paraglide JS se vuoi la configurazione documentata da TanStack, funzioni di messaggio tipizzate e tree-shaking a livello di singolo messaggio, e hai già un modo per popolare i file JSON. Scegli react-i18next se devi riutilizzare cataloghi i18next provenienti da un&#39;altra app. Scegli Lingui se i tuoi traduttori lavorano con file PO. Scegli General Translation se vuoi che i testi restino inline nei componenti e che le traduzioni vengano generate a partire da essi e mantenute sempre aggiornate. (Per un confronto più approfondito, consulta [General Translation vs. Paraglide JS](/kb/general-translation-vs-paraglide).)

`gt-tanstack-start` è sperimentale: secondo la documentazione di General Translation potrebbe introdurre modifiche incompatibili e non è ancora consigliato in produzione. Se ti serve subito una configurazione React stabile, consulta [Come traduco un&#39;app React?](/kb/translate-react-app).

## Aggiungere General Translation a TanStack Start

In questa guida aggiungerai lo spagnolo e il francese a una pagina, tradurrai una funzione server e infine sposterai ciascuna lingua su un URL dedicato. La guida è stata testata con un&#39;app generata da `npx @tanstack/cli@latest create` (`@tanstack/react-start` 1.169.4), `gt-tanstack-start@11.4.16` e `gt@2.26.11`. Il pacchetto richiede `@tanstack/react-start` 1.159.0 o versioni successive ed è disponibile solo come ESM.

La [procedura guidata di configurazione](/docs/cli/reference/commands/init), `npx gt@2.26.11 init`, applica le stesse modifiche dei passaggi da 1 a 4: installa il pacchetto, scrive il loader, il middleware, la chiamata al router e la rotta radice, e segnala tutto ciò che non è in grado di modificare in modo sicuro. Puoi esaminarne il diff oppure seguire i passaggi manualmente.

### 1. Installa la libreria e la CLI

```bash
npm install gt-tanstack-start@11.4.16
npm install --save-dev gt@2.26.11
```

`gt-tanstack-start` esporta i componenti React condivisi, come [`<T>`](/docs/react/reference/components/t) e [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), oltre agli helper lato server. La CLI `gt` individua i testi sorgente e genera i file di traduzione.

### 2. Imposta le lingue

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

Salva l&#39;output in `src/` così Vite può importare i file. Poi aggiungi un loader:

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

### 3. Registra il middleware delle richieste

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

// Mantieni la protezione CSRF di TanStack Start per le funzioni server.
const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

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

Il [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) di General Translation risolve l&#39;impostazione regionale una sola volta per richiesta, cercandola prima nel cookie dell&#39;impostazione regionale, poi in `Accept-Language` e infine in `defaultLocale`, e la salva nel cookie. Ogni richiesta mantiene la propria impostazione regionale, anche quando più richieste vengono renderizzate in parallelo.

### 4. Inizializza la libreria e idrata la rotta radice

Aggiungi l&#39;inizializzatore al file `src/router.tsx` esistente, a livello di modulo:

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

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

// ... il tuo getRouter() esistente
```

Quindi carica l&#39;impostazione regionale e le relative traduzioni nella rotta radice e passale entrambe a [`<GTProvider>`](/docs/react/reference/components/gt-provider):

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

export const Route = createRootRoute({
  // Viene eseguito sul server alla prima richiesta, quindi l'HTML arriva già tradotto.
  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 della richiesta sul server e il cookie nel browser, in modo che i due rendering coincidano. Impostando `lang={locale}` si sostituisce il valore `lang="en"` hardcoded nella shell dello starter.

### 5. Contrassegna i contenuti da tradurre

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

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

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

  return (
    <main>
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} />
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) traduce il titolo e il paragrafo come un&#39;unica unità, usando il markup come contesto. [`useGT`](/docs/react/reference/hooks/use-gt) si occupa delle stringhe negli attributi. Per nomi, conteggi e date all&#39;interno di [`<T>`](/docs/react/reference/components/t), usa i [componenti per variabili e formattazione](/docs/react/guides/formatting-variables).

### 6. Genera traduzioni

Accedi con [`npx gt login`](/docs/cli/reference/commands/login), imposta `GT_PROJECT_ID` (oppure `projectId` in `gt.config.json`) ed esegui [`npx gt translate`](/docs/cli/reference/commands/translate). Il comando genera `src/_gt/es.json` e `src/_gt/fr.json`. La generazione prevede una [tariffazione a consumo](https://generaltranslation.com/pricing).

Per provare la configurazione senza un account, esegui [`npx gt generate`](/docs/cli/reference/commands/generate). Il comando crea gli stessi file con il testo di origine in inglese, che potrai poi modificare a mano. Un&#39;impostazione regionale ancora priva di file renderizza il testo di origine e registra un avviso per segnalare che non è stato possibile caricarne le traduzioni.

### 7. Avvia l&#39;app e cambia lingua

Esegui `npm run dev` e seleziona Español nel selettore. La scelta viene salvata nel cookie dell&#39;impostazione regionale, la pagina si ricarica e il server renderizza la versione in spagnolo. Nell&#39;app di test, una build di produzione ha restituito `<html lang="es">` con titolo e segnaposto in spagnolo per una richiesta con `Accept-Language: es`, e `<html lang="en">` con i contenuti in inglese per una richiesta senza preferenze di lingua.

## Tradurre nelle funzioni server e nei metadati

[`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) traduce le stringhe all&#39;interno di una funzione server, usando l&#39;impostazione regionale della richiesta:

```tsx title="src/routes/account.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { getGT } from 'gt-tanstack-start';

const loadAccount = createServerFn({ method: 'GET' }).handler(async () => {
  const gt = await getGT();
  return { title: gt('Your account') };
});

export const Route = createFileRoute('/account')({
  loader: () => loadAccount(),
  // Il titolo tradotto diventa anche il <title> della pagina.
  head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }),
  component: () => <h1>{Route.useLoaderData().title}</h1>,
});
```

Sul server, questi helper generano un errore se usati al di fuori di una richiesta gestita da [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), ad esempio a livello di modulo. La guida [Uso delle funzioni server](/docs/react/tanstack-start/using-server-functions) tratta anche le voci del dizionario e i messaggi registrati.

## Assegnare a ogni lingua un proprio URL

La configurazione precedente serve tutte le lingue dallo stesso URL, scelto in base al cookie o alla lingua del browser. I motori di ricerca indicizzano una sola lingua per URL, quindi [le pagine pubbliche richiedono un prefisso](/kb/locale-routing-seo), ad esempio `/es/about`. Sposta le route in un segmento facoltativo, ad esempio `src/routes/{-$locale}/index.tsx` con `createFileRoute('/{-$locale}/')`, quindi attiva il routing delle impostazioni regionali:

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

A quel punto il middleware controlla prima il percorso e il selettore porta all&#39;URL con prefisso. Nell&#39;app di test, `/es` e `/es/account` sono stati renderizzati in spagnolo con `<html lang="es">`, mentre `/` è stato renderizzato in inglese. Per chi torna sul sito, un URL senza prefisso continua a seguire il cookie, mentre i [link `hreflang`](/kb/what-is-hreflang) vanno aggiunti manualmente nell&#39;`head` di ogni route. (Consulta la [configurazione del routing delle impostazioni regionali](/docs/react/tanstack-start/setup#locale-routing).)

## Rilascia e mantieni aggiornate le traduzioni

Traduci prima di ogni build, così i nuovi testi vengono rilasciati in tutte le lingue:

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

[`gt validate`](/docs/cli/reference/commands/validate) fa fallire la build sui contenuti che comprometterebbero la traduzione, prima di qualsiasi chiamata API. In CI, imposta `GT_PROJECT_ID` e una chiave API di progetto come `GT_API_KEY` con i permessi **File &gt; Scrittura** e **Coda di traduzione &gt; Abilitata** ([credenziali della CLI](/docs/cli/guides/configuring#credentials)). Le esecuzioni successive traducono solo i contenuti sorgente nuovi o modificati.

I revisori possono modificare qualsiasi stringa nell&#39;[Editor di traduzione](/docs/platform/dashboard/guides/reviewing-translations) di General Translation, mentre [`npx gt save-local`](/docs/cli/reference/commands/save-local) reinvia le modifiche apportate direttamente nei file JSON, in modo che le esecuzioni successive le conservino. Un [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) raccoglie il tuo Glossario e i tuoi prompt personalizzati, così nomi dei prodotti e tono restano coerenti tra questa app, la tua documentazione e gli altri tuoi progetti. [Locadex](/docs/platform/locadex/guides/configuring-automations), l&#39;agente IA di General Translation, supporta le app TanStack Start e può tradurre i nuovi testi tramite pull request.

## Domande frequenti

### TanStack Start ha un supporto i18n integrato?

No. TanStack Router offre segmenti di impostazione regionale facoltativi e riscrittura degli URL, mentre Start mette a disposizione middleware e loader; messaggi, rilevamento del locale e traduzioni, però, devono essere gestiti da una libreria.

### Posso usare react-i18next con TanStack Start?

Sì, in quanto libreria React. TanStack non lo documenta e la guida SSR di react-i18next cita solo le integrazioni per Next.js, Remix e Gatsby, quindi l&#39;istanza per-request e l&#39;idratazione lato client dovrai configurarle da solo.

### gt-tanstack-start è pronto per la produzione?

Non ancora: General Translation lo considera sperimentale. Fissa la versione e consulta il changelog prima di aggiornare.

## Punti chiave

* TanStack Start non include un livello i18n; i segmenti facoltativi `/{-$locale}`, il middleware `createStart` e i loader radice sono i punti in cui agganciarne uno.
* Risolvi l&#39;impostazione regionale per ogni richiesta sul server, idrata il client con gli stessi messaggi e imposta `<html lang>` dal loader anziché usare il valore `lang="en"` hardcoded nello starter.
* Paraglide JS è la libreria documentata da TanStack; questa, react-i18next e Lingui si limitano a renderizzare le traduzioni che fornisci tu.
* Il pacchetto sperimentale `gt-tanstack-start` di General Translation aggiunge [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), [`initializeGT`](/docs/react/reference/config#initialize) e [`<GTProvider>`](/docs/react/reference/components/gt-provider), mantiene i testi inline in [`<T>`](/docs/react/reference/components/t), mentre [`npx gt translate`](/docs/cli/reference/commands/translate) scrive `src/_gt/[locale].json`.
* Aggiungi `"localeRouting": true` con un segmento facoltativo `{-$locale}` quando ogni lingua deve avere un proprio URL indicizzabile.

## Related questions

- [Come si aggiunge l'i18n a un'app Next.js con App Router?](https://generaltranslation.com/it/kb/add-i18n-to-nextjs.mdx): Inizia con gt init per configurare General Translation in un progetto App Router supportato, poi contrassegna il contenuto di origine, genera le traduzioni e verifica il cambio di lingua. gt-next mantiene i testi nel JSX insieme al contesto di traduzione; la CLI, l'editor della Dashboard e Locadex si occupano di generazione, revisione e aggiornamenti continui. Questa guida mostra anche la configurazione esplicita con file locali.
- [General Translation o Paraglide JS: quale scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-paraglide.mdx): Scegli General Translation per mantenere i testi inline e generare traduzioni basate sulla struttura dei tuoi componenti React, su una terminologia condivisa e sulla revisione nella Dashboard. Scegli Paraglide JS per funzioni di messaggio compilate e tipizzate, con tree-shaking per singolo messaggio. Paraglide renderizza i tuoi cataloghi; General Translation collega i testi sorgente alla generazione delle traduzioni e ai successivi aggiornamenti.
- [Qual è la migliore libreria i18n per un'app React?](https://generaltranslation.com/it/kb/best-react-i18n-library.mdx): Le quattro principali librerie i18n per React sono gt-react di General Translation, react-i18next, Lingui e React Intl. Tutte e quattro renderizzano e formattano le traduzioni, ma solo gt-react è anche in grado di generarle, a partire dai testi scritti inline nel tuo JSX. Scegli react-i18next per continuare a usare i cataloghi e i plugin di i18next, Lingui per l'estrazione in cataloghi compilati e React Intl per FormatJS e ICU MessageFormat.
- [Reindirizzamenti per lingua e SEO: URL, cookie o Accept-Language?](https://generaltranslation.com/it/kb/locale-routing-seo.mdx): Lascia che sia l'URL a stabilire la lingua di ogni pagina che vuoi far indicizzare, perché Googlebot non invia alcuna intestazione Accept-Language ed esegue la scansione soprattutto da indirizzi statunitensi. Usa la scelta salvata in un cookie e, in subordine, Accept-Language solo per decidere verso quale pagina reindirizzare una radice neutra come /, con un reindirizzamento temporaneo 302 o 307.
- [Come si traduce un'app React?](https://generaltranslation.com/it/kb/translate-react-app.mdx): Tradurre un'app React significa internazionalizzarne i componenti affinché vengano renderizzati nella lingua dell'utente, quindi tradurre ogni stringa in ciascuna lingua supportata. gt-react di General Translation traduce il JSX in-place nel componente `<T>`, mentre npx gt translate genera un file per ogni lingua.

## Previous and next questions

- Previous question: [Come mantenere coerente la terminologia nella traduzione con l'AI?](https://generaltranslation.com/it/kb/ai-translation-glossary.mdx)
- Next question: [Come si crea una mappa del sito per un sito web multilingue?](https://generaltranslation.com/it/kb/multilingual-sitemap.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.