# General Translation Knowledge Base: Come si aggiunge l'i18n a un'app Next.js con App Router?
URL: https://generaltranslation.com/it/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 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.
Category: Internazionalizzazione
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

In questa guida aggiungeremo inglese, spagnolo e francese a una piccola pagina di progetto, includendo un Componente server, un Client Component e un selettore della lingua. La lingua viene selezionata tramite cookie; gli URL con prefisso dell'impostazione regionale e la SEO multilingue richiedono un passaggio a parte.

`gt-next` di General Translation è pensato per Next.js App Router. Mantiene il testo sorgente all'interno del JSX che gli dà significato e collega quel contenuto alla generazione delle traduzioni. Usa la [prop `context`](/docs/react/reference/components/t#context) per chiarire le formulazioni ambigue e assegna [termini del Glossario e prompt personalizzati](/docs/platform/dashboard/guides/defining-context-for-translations) per definire terminologia e tono. Il flusso di lavoro di build descritto di seguito si occupa poi di aggiornare le traduzioni man mano che il sorgente cambia.

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51 s)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## Prima di iniziare

Usa un progetto TypeScript esistente basato su App Router con una directory `src/app`. Gli esempi fanno riferimento a Next.js 16 e usano npm. Next.js 16 richiede Node.js 20.9 o versioni successive. Se parti da zero, segui prima la [guida all&#39;installazione di Next.js](https://nextjs.org/docs/app/getting-started/installation). Per le app basate su Pages Router, consulta l&#39;[Avvio rapido per Pages Router](/docs/react/nextjs-pages-router-quickstart).

L&#39;esempio esplicito usa `gt-next@11.4.12` e `gt@2.26.5`. La libreria, con licenza MIT, può renderizzare le traduzioni che fornisci tu anche senza un account. Per le traduzioni generate dal servizio, usa un progetto GT e il [login tramite CLI o una chiave di tooling con ambito limitato](/docs/cli/guides/configuring#credentials). Per le build automatizzate, usa una chiave conservata nel secret store della tua CI.

## Inizia con il comando di configurazione

Avvia la procedura guidata di configurazione nella directory dell&#39;app:

```bash
npx gt@2.26.5 init
```

Scegli la configurazione del framework React per la tua app con App Router, le lingue sorgente e di destinazione e la consegna locale o tramite CDN. La procedura guidata installa `gt-next`, aggiunge [`GTProvider`](/docs/react/reference/components/gt-provider) e [`withGTConfig`](/docs/react/nextjs/config) e crea `gt.config.json`. Con la consegna locale, crea anche un loader delle traduzioni. La riscrittura del framework è sperimentale: esamina il diff generato, soprattutto in corrispondenza dei provider e dei wrapper di configurazione esistenti. [Riferimento della configurazione](/docs/cli/reference/commands/init).

Resta comunque a te contrassegnare i contenuti dell&#39;applicazione e generarne le traduzioni. Se preferisci che sia un agente di programmazione a portare a termine l&#39;attività fino alla verifica, usa [Configurazione per agenti](https://generaltranslation.com/agent-prompt.md).

La configurazione esplicita riportata di seguito usa `src/_gt/[locale].json`. L&#39;output locale predefinito della procedura guidata è `public/_gt/[locale].json`: mantieni allineati il loader generato e il relativo percorso di output, oppure segui la configurazione esplicita come alternativa completa.

## Configura esplicitamente la libreria e scrivi la pagina

### 1. Installa l&#39;SDK e la CLI

Esegui questi comandi nella directory dell&#39;applicazione:

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` renderizza le traduzioni nell&#39;applicazione. `gt` è lo strumento da riga di comando che serve a raccogliere e tradurre il contenuto di origine. [Avvio rapido ufficiale per Next.js](/docs/react/nextjs-quickstart).

### 2. Configura Next.js e le lingue

Racchiudi la configurazione Next.js esistente con [`withGTConfig`](/docs/react/nextjs/config). Mantieni le impostazioni già presenti e integra questa funzione con gli altri wrapper di configurazione che stai già usando.

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

export default withGTConfig({});
```

Crea questo file nella radice del progetto:

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

L&#39;inglese è la lingua di origine. Lo spagnolo e il francese sono le lingue di destinazione. Il percorso di output indica alla CLI dove salvare le traduzioni generate.

### 3. Aggiungi un loader delle traduzioni locale

Crea `src/loadTranslations.ts`. Il plugin di configurazione rileva questo file e lo usa per caricare i file delle impostazioni regionali generati:

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

Questa configurazione include le traduzioni nel bundle dell&#39;applicazione, quindi in produzione non servono chiamate a General Translation in fase di runtime per questo contenuto. Gli aggiornamenti delle traduzioni vengono rilasciati insieme alla build. [Archiviazione locale delle traduzioni](/docs/react/guides/storing-translations).

I file non esistono ancora. Completa la pagina e generali al passaggio 6 prima di avviare il server di sviluppo, altrimenti l&#39;import del loader potrebbe non andare a buon fine.

### 4. Aggiungi il provider al layout radice

Modifica `src/app/layout.tsx` come mostrato di seguito. Mantieni gli stili, i font, i metadati e gli altri provider già presenti.

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) risolve la lingua corrente sul server. [`GTProvider`](/docs/react/reference/components/gt-provider) fornisce il contesto di traduzione all&#39;intera applicazione, inclusi i suoi componenti interattivi.

### 5. Tradurre JSX e gli attributi di input

Aggiungi la pagina seguente, che resta un Componente server. [`T`](/docs/react/reference/components/t) contrassegna da tradurre l&#39;intestazione e il paragrafo statici, mentre [`LocaleSelector`](/docs/react/reference/components/locale-selector) fornisce il menu a discesa per la scelta della lingua.

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

Crea il campo di ricerca come Client Component. Usa [`useGT`](/docs/react/reference/hooks/use-gt) per gli attributi con valori stringa, come i segnaposto e le etichette di accessibilità:

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

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

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) restituisce direttamente la funzione di traduzione. In un Componente server asincrono, usa invece [`getGT`](/docs/react/nextjs/reference/functions/get-gt) da `gt-next/server`.

Non inserire valori dinamici come espressioni grezze all&#39;interno di [`T`](/docs/react/reference/components/t). Per aggiungere nomi, conteggi o rami, usa gli appositi [componenti di variabile e formattazione](/docs/react/guides/formatting-variables).

## Genera traduzioni e verifica il risultato

### 6. Genera l&#39;output tradotto

Per la traduzione automatica, accedi con [`gt login`](/docs/cli/reference/commands/login) e configura l&#39;ID progetto, oppure inserisci una chiave API del progetto e l&#39;ID progetto in `.env.local`:

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="your-project-api-key"
```

Mantieni la chiave privata e tieni il file fuori dal controllo di versione. Non esporre `GT_API_KEY` tramite una variabile `NEXT_PUBLIC_`. La chiave per gli strumenti richiede le autorizzazioni di lettura/scrittura dei file e di accesso alla coda di traduzione, oltre all&#39;accesso al contesto, se utilizzato. Consulta la [documentazione sulle chiavi API](/docs/platform/dashboard/reference/api-keys).

Genera le traduzioni:

```bash
npx gt translate
```

Il comando invia il lavoro di traduzione a General Translation e scrive i file delle impostazioni regionali nel percorso di output configurato. Puoi rivedere il testo generato nell&#39;[Editor di traduzione della dashboard](/docs/platform/dashboard/guides/reviewing-translations). Se modifichi in locale le traduzioni scaricate, [`gt save-local`](/docs/cli/reference/commands/save-local) sincronizza le correzioni con la piattaforma. La generazione tramite il servizio prevede una [tariffazione a consumo](https://generaltranslation.com/pricing).

Se vuoi provare la libreria senza chiamare il servizio di traduzione, esegui invece questo comando:

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) crea modelli contenenti il testo di origine; **non traduce quel testo**. Modifica i valori di testo in `src/_gt/es.json` e `src/_gt/fr.json`, mantenendo invariate le chiavi generate e la struttura JSX. Ad esempio, nel file spagnolo traduci l&#39;intestazione con “Encuentra tu próximo proyecto” e l&#39;etichetta di ricerca con “Buscar proyectos”. Traduci il testo rimanente prima di considerare completi questi file.

Dopo aver modificato il contenuto di origine, esegui di nuovo [`gt generate`](/docs/cli/reference/commands/generate) e controlla i file di destinazione. Il comando conserva i valori di destinazione esistenti, aggiunge le nuove voci con il testo di origine e rimuove quelle non più presenti nella sorgente.

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

```bash
npm run dev
```

Apri l&#39;indirizzo mostrato da Next.js. Seleziona spagnolo e francese nel menu a discesa. Verifica che il titolo, il paragrafo, il segnaposto e l&#39;etichetta accessibile del campo di input cambino. Ricarica la pagina per verificare che la lingua selezionata venga mantenuta, quindi torna all&#39;inglese.

Se il selettore cambia ma il testo resta in inglese, controlla i file della lingua di destinazione. I modelli di origine generati da [`gt generate`](/docs/cli/reference/commands/generate) restano in inglese finché non li traduci. Se la compilazione della pagina non riesce perché manca un file di impostazione regionale, esegui di nuovo il comando di generazione appropriato prima di riavviare il server di sviluppo.

## Build per la produzione

Esegui [`gt validate`](/docs/cli/reference/commands/validate) per individuare gli errori di sintassi nelle traduzioni prima di inviare una richiesta di traduzione ospitata. Le [regole ESLint](/docs/react/guides/linting-your-code) di GT offrono ulteriori controlli in fase di sviluppo. Se hai [configurato la traduzione in fase di sviluppo](/docs/react/guides/configuring#delivery), puoi anche visualizzare in anteprima il contenuto tradotto mentre modifichi il codice.

Per il flusso di lavoro di traduzione automatica, integra questo comando di build negli script esistenti del tuo `package.json`:

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

Imposta `GT_PROJECT_ID` e `GT_API_KEY` nell&#39;ambiente di build. Assicurati che la CLI, installata come dipendenza di sviluppo, sia disponibile durante la build. Aggiungi `src/_gt/` a `.gitignore` se la tua build rigenera ogni volta l&#39;output delle traduzioni.

Se hai scelto la traduzione manuale, mantieni i file tradotti sotto controllo di versione oppure recuperali dalla tua pipeline di traduzione. Esegui `next build` solo quando questi file sono disponibili. Non trattare le traduzioni gestite manualmente come output riproducibile da ignorare: rischieresti di eliminarne l&#39;unica copia.

Dopo la build, avvia l&#39;app in produzione e ripeti la verifica del cambio di lingua. In questo modo verifichi i file che verranno effettivamente distribuiti, senza affidarti solo al comportamento in fase di sviluppo.

Il [flusso di lavoro di traduzione incrementale](/docs/cli/guides/generating-translations#retranslate) traduce i contenuti sorgente modificati e riutilizza le traduzioni corrispondenti delle versioni precedenti. Per automatizzare anche le modifiche al repository, configura [Locadex](/docs/platform/locadex/guides/configuring-automations) in modo che internazionalizzi la nuova UI, generi le traduzioni o sincronizzi le modifiche alle impostazioni regionali tramite pull request. Scegli le impostazioni di attivazione e revisione più adatte al tuo processo di rilascio.

Per aggiornare le traduzioni senza ricompilare l&#39;applicazione, scegli la [consegna tramite CDN](/docs/react/nextjs/config) al posto del loader locale. In questo modo, le modifiche alle traduzioni pubblicate potranno raggiungere l&#39;applicazione distribuita in base alle sue impostazioni di versione e di cache.

Per le pagine pubbliche che richiedono URL distinti per ogni lingua, prosegui con il [routing delle impostazioni regionali con App Router](/docs/react/nextjs/app-router-middleware). L&#39;esempio basato su cookie illustrato qui non crea pagine `/es` e `/fr` né configura URL canonical e metadati `hreflang`.

## Un prompt per il tuo agente di programmazione

Parti dal [prompt di configurazione ufficiale](https://generaltranslation.com/agent-prompt.md), che viene mantenuto sempre aggiornato, e aggiungi poi questa descrizione della funzionalità:

```text
Usa l'inglese come lingua di origine, con spagnolo e francese come lingue di destinazione.
Localizza la pagina del progetto usando traduzioni incluse nel bundle locale. Mantieni
i provider e le route esistenti. Includi titolo, paragrafo, campo di ricerca,
etichetta accessibile e un selettore di lingua. Usa la terminologia condivisa del progetto.
Verifica il cambio di lingua, la persistenza dopo il ricaricamento, i contenuti server-rendered,
gli attributi lato client e la build di produzione. Indica cosa è stato effettivamente testato
e cosa richiede ancora una revisione linguistica. Non eseguire il deploy né il merge.
```

Per una panoramica più ampia del flusso di lavoro, leggi [i18n senza file di traduzione](/kb/i18n-without-translation-files) e [usare un agente di programmazione](/kb/ai-agent-i18n-setup).

## Related questions

- [Posso fare i18n senza file di traduzione?](https://generaltranslation.com/it/kb/i18n-without-translation-files.mdx): Sì. Le librerie gt-react e gt-next di General Translation gestiscono l'i18n in React e Next.js senza chiavi di traduzione e senza dover mantenere un file JSON per ogni lingua. I testi restano inline nel JSX all'interno del componente `<T>` e il comando gt translate genera le traduzioni per ogni lingua durante la build, sfruttando il contesto del tuo codice. Locadex può mantenerle aggiornate tramite pull request.
- [Come si internazionalizza un'app con Cursor o Claude Code?](https://generaltranslation.com/it/kb/ai-agent-i18n-setup.mdx): Inizia con il prompt Setup for Agents di General Translation in Cursor o Claude Code, scegli una funzionalità e le lingue di destinazione, poi lascia che sia l'agente a implementare e verificare il risultato. L'accesso tramite browser, la documentazione leggibile dalle macchine e gli strumenti MCP collegano la configurazione alla traduzione e alla revisione. Usa Locadex per automatizzare la localizzazione continua tramite pull request.
- [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 mantengo le traduzioni aggiornate a ogni distribuzione?](https://generaltranslation.com/it/kb/translations-in-ci.mdx)
- Next question: [Come si formattano numeri, date e valute per ogni impostazione regionale?](https://generaltranslation.com/it/kb/format-numbers-dates-currencies.mdx)

## Sitemap

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