# General Translation Knowledge Base: Come si migra da react-i18next a gt-react?
URL: https://generaltranslation.com/it/kb/migrate-from-react-i18next.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Installa gt-react accanto a react-i18next, condividi un unico cookie dell'impostazione regionale e sposta un componente alla volta dalle chiavi t() e da `<Trans>` a testo inline in `<T>` e useGT. General Translation traduce il testo spostato usando il relativo JSX come contesto, e il tuo team può correggerlo nella Dashboard. I componenti non ancora migrati mantengono le traduzioni di react-i18next già revisionate.
Category: Internazionalizzazione
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

react-i18next renderizza le traduzioni che scrivi in un file JSON per ogni lingua e namespace. gt-react renderizza il testo scritto inline nei tuoi componenti, mentre General Translation genera le traduzioni con [`npx gt translate`](/docs/cli/reference/commands/translate). La migrazione consiste nel sostituire ogni ricerca `t('key')` con il testo di origine a cui fa riferimento, un componente alla volta, mentre le due librerie convivono.

Non è necessario migrare per usare General Translation. La CLI `gt` rileva `i18next` nel tuo `package.json` e ne traduce i file JSON lasciando intatta la sintassi `{{variable}}` di i18next. Conviene migrare quando vuoi tenere il testo accanto al JSX che lo renderizza, senza dover dare un nome alle chiavi né sincronizzare a mano i file di ogni lingua.

## Come si mappano le API di react-i18next su gt-react?

| react-i18next                                  | gt-react                                                                                                                                                                                                          |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `i18n.init({ lng, supportedLngs, resources })` | `gt.config.json` (`defaultLocale`, `locales`) e [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) nel file di ingresso                                                                             |
| `I18nextProvider` / `initReactI18next`         | Nessun provider in una single-page app (SPA); le app server-rendered usano [`initializeGT`](/docs/react/reference/config#initialize) con [`GTProvider`](/docs/react/reference/components/gt-provider)             |
| `<Trans i18nKey="..." components={...}>`       | [`<T>`](/docs/react/reference/components/t) che racchiude il JSX vero e proprio, con link e markup scritti inline                                                                                                 |
| `t('key')` per le stringhe                     | [`useGT`](/docs/react/reference/hooks/use-gt) con la stringa di origine, oppure [`useTranslations`](/docs/react/reference/hooks/use-translations) per continuare a usare le chiavi                                |
| Interpolazione `{{name}}`                      | [`<Var>`](/docs/react/reference/components/var) in JSX; `{name}` nelle stringhe                                                                                                                                   |
| `key_one` / `key_other` con `count`            | [`<Plural>`](/docs/react/reference/components/plural) in JSX; ICU `{n, plural, ...}` nelle stringhe                                                                                                               |
| `useTranslation('ns')` o `keyPrefix`           | `useTranslations('ns')` circoscrive le ricerche a un prefisso                                                                                                                                                     |
| `{{val, number}}` e altri formattatori         | [`<Num>`](/docs/react/reference/components/num), [`<Currency>`](/docs/react/reference/components/currency) e [`<DateTime>`](/docs/react/reference/components/datetime)                                            |
| `i18n.changeLanguage()` / `i18n.language`      | [`useSetLocale`](/docs/react/reference/hooks/use-set-locale) / [`useLocale`](/docs/react/reference/hooks/use-locale), oppure il componente [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) |
| `i18next-browser-languagedetector`             | Integrato: prima il cookie `generaltranslation.locale`, poi le lingue del browser                                                                                                                                 |
| `fallbackLng`                                  | In assenza di una traduzione, viene renderizzato il testo di origine                                                                                                                                              |

## Passaggio 1: Installa gt-react insieme a react-i18next

Segui la [Guida rapida per SPA React](/docs/react/react-spa-quickstart) per un&#39;app Vite o webpack, oppure la [Guida rapida a React](/docs/react/react-quickstart) per un&#39;app server-rendered. In una SPA, la configurazione prevede questi passaggi:

1. Installa `gt-react` e la CLI `gt` come dipendenza di sviluppo.
2. Crea `gt.config.json` con la stessa locale di origine e le stesse impostazioni locali di destinazione della tua config di i18next.
3. Aggiungi una funzione [`loadTranslations`](/docs/react/reference/functions/load-translations) e chiama [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) in un file di ingresso che importi il resto dell&#39;app solo dopo il caricamento delle traduzioni.
4. Accedi con [`npx gt login`](/docs/cli/reference/commands/login) e imposta il tuo ID progetto.

Lascia invariati `i18n.init` e i tuoi file JSON. Per gli utenti non cambia nulla finché non migri un componente. Se `gt.config.json` elenca i tuoi file i18next sotto `files`, rimuovi quella voce, così che ogni stringa abbia un&#39;unica fonte di traduzione: i file JSON mantengono le traduzioni per i componenti non ancora migrati, mentre i testi nuovi o modificati vanno inline in gt-react.

## Passaggio 2: Mantenere un unico locale attivo

Due librerie possono trovarsi in disaccordo sulla lingua dell&#39;utente. Usa gt-react come selettore della lingua e configura i18next in modo che legga lo stesso cookie:

```ts title="src/i18n.ts"
import i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    // ...le opzioni che hai già
    detection: {
      order: ['cookie', 'navigator'],
      lookupCookie: 'generaltranslation.locale', // il cookie scritto da gt-react
      caches: [],
    },
  });
```

Sostituisci il vecchio menu di selezione della lingua con [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) di gt-react oppure con un controllo che chiama [`useSetLocale`](/docs/react/reference/hooks/use-set-locale). In una SPA, il cambio di lingua scrive il cookie e ricarica la pagina, così entrambe le librerie si avviano nella nuova lingua. Prima di procedere, verifica la navigazione tra le schermate già migrate e quelle non ancora migrate.

## Passaggio 3: sposta un componente alla volta

Copia il testo in lingua sorgente dal tuo JSON nel componente, mantenendo le variabili come variabili. Prima:

```json title="public/locales/en/translation.json"
{
  "inbox": "Hi {{name}}, <link>open your inbox</link>.",
  "messages_one": "You have {{count}} message",
  "messages_other": "You have {{count}} messages"
}
```

```tsx title="src/Inbox.tsx"
import { Trans, useTranslation } from 'react-i18next';

export function Inbox({ name, count }: { name: string; count: number }) {
  const { t } = useTranslation();
  return (
    <>
      <Trans i18nKey="inbox" values={{ name }} components={{ link: <a href="/inbox" /> }} />
      <p>{t('messages', { count })}</p>
    </>
  );
}
```

Dopo:

```tsx title="src/Inbox.tsx"
import { T, Var, Plural, Num } from 'gt-react';

export function Inbox({ name, count }: { name: string; count: number }) {
  return (
    <T>
      Hi <Var>{name}</Var>, <a href="/inbox">open your inbox</a>.
      <p>
        <Plural
          n={count}
          singular={<>You have <Num>{count}</Num> message</>}
          plural={<>You have <Num>{count}</Num> messages</>}
        />
      </p>
    </T>
  );
}
```

Il link resta un vero elemento `<a>` invece di diventare un segnaposto numerato. General Translation traduce l&#39;intero blocco usando la sua struttura come contesto e, a partire dalle forme `singular` e `plural` che scrivi, genera le forme richieste da ciascuna lingua di destinazione, come le forme `few` e `many` del polacco. [`<Plural>`](/docs/react/reference/components/plural) sceglie poi quella giusta in base a ogni quantità.

Per le stringhe al di fuori di JSX, come i segnaposto e i toast, usa [`useGT`](/docs/react/reference/hooks/use-gt). Le variabili si scrivono tra parentesi graffe singole e puoi aggiungere un contesto per le parole ambigue:

```tsx
import { useGT } from 'gt-react';

function Search({ count }: { count: number }) {
  const gt = useGT();
  return <input placeholder={gt('Search {count} projects', { count })} />;
}

// In un gestore di eventi, con un suggerimento per il traduttore:
toast(gt('Saved {fileName}', { fileName, $context: 'toast after saving a file' }));
```

Il primo argomento deve essere una stringa statica, non un template literal né una concatenazione. Dopo ogni batch di componenti, esegui [`npx gt translate`](/docs/cli/reference/commands/translate) e controlla tutte le impostazioni regionali.

## Puoi mantenere le tue chiavi di traduzione?

Sì. Sposta le chiavi in un unico [dizionario](/docs/react/guides/translating-with-dictionaries) di gt-react e sostituisci `useTranslation` con [`useTranslations`](/docs/react/reference/hooks/use-translations). La chiamata di ricerca resta invariata:

```tsx
// Prima
import { useTranslation } from 'react-i18next';
const { t } = useTranslation();

// Dopo
import { useTranslations } from 'gt-react';
const t = useTranslations();

return <h1>{t('home.welcome', { name })}</h1>;
```

Le voci del dizionario usano ICU MessageFormat, quindi il JSON richiede tre modifiche:

* `{{name}}` diventa `{name}`.
* Le chiavi plurali vengono unite in un&#39;unica voce: `"messages": "You have {count, plural, one {# message} other {# messages}}"`.
* I file dei namespace vengono uniti in un unico `dictionary.json`, in cui ogni namespace diventa una chiave di primo livello. `useTranslation('settings')` diventa `useTranslations('settings')`.

[`npx gt validate`](/docs/cli/reference/commands/validate) segnala le voci che non rispettano la sintassi ICU. A differenza di i18next, che restituisce la chiave quando una voce manca, [`useTranslations`](/docs/react/reference/hooks/use-translations) solleva un&#39;eccezione, quindi assicurati che id e voci restino sincronizzati.

## Cosa succede alle traduzioni esistenti?

I componenti che non hai ancora migrato continuano a renderizzare le traduzioni react-i18next già revisionate, quindi una migrazione graduale interessa solo le schermate su cui intervieni. I testi che sposti in [`<T>`](/docs/react/reference/components/t), [`useGT`](/docs/react/reference/hooks/use-gt) o in un dizionario gt-react ricevono nuove traduzioni da [`npx gt translate`](/docs/cli/reference/commands/translate), che tengono conto della struttura JSX di [`<T>`](/docs/react/reference/components/t) e dell&#39;eventuale contesto che aggiungi. Il Glossario e i Prompt Personalizzati di un [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) mantengono coerenti la tua terminologia e il tuo tono. I revisori possono poi correggere qualsiasi formulazione nella [dashboard](/docs/platform/dashboard/guides/reviewing-translations).

Se ogni traduzione revisionata deve restare esattamente com&#39;è, mantieni react-i18next e lascia invece che General Translation ne traduca i file JSON. (Vedi [General Translation vs. i18next](/kb/general-translation-vs-i18next).)

## Passaggio 4: Rimuovere react-i18next

Quando la ricerca di `useTranslation`, `<Trans` e `i18next` non restituisce più alcun risultato, rimuovi il file `i18n.init`, i file JSON, il rilevatore della lingua e le dipendenze `i18next` e `react-i18next`. Poi aggiungi [`npx gt translate`](/docs/cli/reference/commands/translate) alla tua build o alla [CI](/kb/translations-in-ci), così i nuovi testi verranno pubblicati già tradotti a ogni rilascio.

## Domande frequenti

### Devo migrare tutto in una volta?

No. Entrambe le librerie possono renderizzare sulla stessa pagina, purché leggano la stessa impostazione regionale. Migra una route o una funzionalità alla volta e rimuovi i18next quando non c&#39;è più alcuna parte del codice che lo utilizza.

### gt-react supporta il rendering server-side?

Sì. Le app React con rendering lato server usano [`initializeGT`](/docs/react/reference/config#initialize) insieme a [`GTProvider`](/docs/react/reference/components/gt-provider) anziché [`initializeGTSPA`](/docs/react/reference/config#initialize-spa). Consulta la [Guida rapida a React](/docs/react/react-quickstart) oppure, se usi `gt-next`, l&#39;[Avvio rapido di Next.js](/docs/react/nextjs-quickstart).

### gt-react è gratuito?

gt-react è distribuito con licenza MIT e renderizza le traduzioni incluse nel bundle senza bisogno di un account. La generazione delle traduzioni con General Translation è invece [a consumo](https://generaltranslation.com/pricing).

## Punti chiave

* Esegui gt-react insieme a react-i18next, configura il rilevatore di lingua di i18next in modo che legga il cookie `generaltranslation.locale` e usa gt-react per cambiare lingua.
* Sostituisci `<Trans>` e le ricerche per chiave con testo inline in [`<T>`](/docs/react/reference/components/t) e [`useGT`](/docs/react/reference/hooks/use-gt); `{{var}}` diventa [`<Var>`](/docs/react/reference/components/var) o `{var}`, e le chiavi plurali diventano [`<Plural>`](/docs/react/reference/components/plural) con `singular` e `plural`.
* I componenti non migrati mantengono le traduzioni già revisionate; il testo migrato viene tradotto usando il relativo JSX come contesto e revisionato nella dashboard.
* Se vuoi mantenere le chiavi, converti i tuoi file JSON in un unico dizionario ICU e usa [`useTranslations`](/docs/react/reference/hooks/use-translations).
* Rimuovi i18next solo quando nessuna parte del codice lo utilizza più, quindi esegui [`npx gt translate`](/docs/cli/reference/commands/translate) nella CI.

## Related questions

- [Alternative a i18next: General Translation vs. i18next](https://generaltranslation.com/it/kb/general-translation-vs-i18next.mdx): Scegli General Translation per mantenere i testi inline nei componenti React e generare le traduzioni sfruttando la struttura JSX e il contesto del prodotto. In alternativa, puoi continuare a usare i18next e affidarti a General Translation per tradurre i cataloghi esistenti. i18next si occupa del rendering dei messaggi e della selezione dei plurali, mentre la generazione delle traduzioni è affidata a un servizio separato.
- [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.
- [Come si traducono le stringhe al di fuori di JSX?](https://generaltranslation.com/it/kb/translate-strings-outside-jsx.mdx): Passa ogni stringa che non è un figlio JSX, come un segnaposto o una costante a livello di modulo, a una funzione di traduzione nel punto in cui viene renderizzata. L'hook useGT di General Translation restituisce questa funzione, mentre msg con useMessages traduce le costanti definite al di fuori di un componente.
- [Come si gestiscono i plurali in React?](https://generaltranslation.com/it/kb/how-to-handle-plurals-in-react.mdx): Per gestire i plurali in React, fornisci per ogni lingua una frase per ciascuna forma plurale e scegli quella corretta in base alle regole del plurale di quella lingua, dato che l'inglese ha 2 forme, il russo 4 e l'arabo 6. Il componente `<Plural>` di General Translation in gt-react e gt-next accetta le tue forme sorgente, e General Translation genera le forme necessarie per ogni lingua di destinazione.
- [Come mantengo le traduzioni aggiornate a ogni distribuzione?](https://generaltranslation.com/it/kb/translations-in-ci.mdx): Esegui la traduzione come passaggio della pipeline prima di ogni build di produzione, così i nuovi testi vengono rilasciati già tradotti insieme alla distribuzione che li introduce. La CLI gt di General Translation lo fa con npx gt translate, usando una chiave API e un ID progetto archiviati come segreti CI.

## Previous and next questions

- Previous question: [Come si migra da next-intl a gt-next?](https://generaltranslation.com/it/kb/migrate-from-next-intl.mdx)
- Next question: [Come si migra da vue-i18n a gt-vue?](https://generaltranslation.com/it/kb/migrate-from-vue-i18n.mdx)

## Sitemap

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