# gt-next: General Translation Next.js SDK: Guida rapida per Pages Router
URL: https://generaltranslation.com/it/docs/next/tutorials/quickstart-pages-router.mdx
---
title: Guida rapida per Pages Router
description: Aggiungi più lingue alla tua app Next.js Pages Router in meno di 10 minuti
---

Al termine di questa guida, la tua app Next.js Pages Router mostrerà contenuti in più lingue, con un selettore della lingua che gli utenti potranno usare.

In Pages Router, `gt-next` funziona tramite `getServerSideProps`: a ogni richiesta, il server determina l&#39;impostazione regionale dell&#39;utente, carica uno snapshot delle traduzioni e li passa a un `<GTProvider>` in `_app.tsx`, così il primo render è già tradotto.

**Prerequisiti:**

* Un&#39;app Next.js che usa **Pages Router**
* Node.js 18+

<Callout type="info">
  **Usi App Router?** Segui invece la [Guida rapida di Next.js](/docs/next) — usa i Server Components e non richiede alcuna configurazione di `getServerSideProps`.
</Callout>

***

## Passaggio 1: Installa i pacchetti

`gt-next` è la libreria che gestisce le traduzioni nella tua app. `gt` è lo strumento CLI che prepara le traduzioni per l&#39;ambiente di produzione.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-next
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-next
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-next
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-next
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## Passaggio 2: Configura la configurazione di Next.js

`gt-next` usa un plugin di Next.js chiamato **`withGTConfig`** per configurare l&#39;internazionalizzazione in fase di build. Avvolgi la configurazione di Next.js esistente con questo plugin:

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

const nextConfig = {};

export default withGTConfig(nextConfig);
```

Questo plugin legge le impostazioni di traduzione e gestisce tutto dietro le quinte. La configurazione è identica sia per App Router sia per Pages Router: non servono flag specifici per il router.

***

## Passaggio 3: Crea un file di configurazione per le traduzioni

Crea un file **`gt.config.json`** nella radice del progetto. Questo file indica alla libreria quali lingue supporta il progetto:

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

* **`defaultLocale`** — la lingua in cui è scritta la tua app (la lingua sorgente).
* **`locales`** — le lingue in cui vuoi tradurre. Scegline una dall&#39;[elenco delle impostazioni regionali supportate](/docs/platform/supported-locales).
* **`files.gt.output`** — dove la CLI salva i file di traduzione. `[locale]` viene sostituito con ciascun codice lingua (ad es. `public/_gt/es.json`).

Aggiungi `public/_gt/` al tuo **`.gitignore`** — questi file sono generati automaticamente, non scritti a mano:

```txt title=".gitignore"
public/_gt/
```

***

## Passaggio 4: Aggiungi una funzione di caricamento per le traduzioni locali

Crea un file **`loadTranslations`** nella radice del progetto (o nella directory `src/`). In questo modo, `gt-next` saprà come caricare i file di traduzione generati dalla CLI:

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

`withGTConfig` rileva automaticamente un file `loadTranslations.[js|ts]` nella radice del progetto o nella directory `src/` — non serve alcuna configurazione aggiuntiva.

<Callout type="info">
  **Perché usare traduzioni locali?** Le traduzioni locali sono incluse nel bundle della tua app, quindi vengono caricate all&#39;istante senza dipendere da servizi esterni. Per maggiori dettagli e per valutare i relativi compromessi, consulta la [guida all&#39;archiviazione locale delle traduzioni](/docs/next/guides/local-tx).
</Callout>

***

## Passaggio 5: Avvolgi getServerSideProps nelle pagine

Avvolgi `getServerSideProps` di ogni pagina con **`withGTServerSideProps`**. A ogni richiesta, determina l&#39;impostazione regionale dell&#39;utente — dal cookie `generaltranslation.locale` se impostato, altrimenti dall&#39;header `Accept-Language` — carica uno snapshot delle traduzioni per quell&#39;impostazione regionale e li inserisce entrambi nelle props della pagina:

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // le tue props
      },
    };
  }
);
```

Se una pagina non richiede props server-side proprie, chiamala senza argomenti:

```tsx title="pages/about.tsx"
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` aggiunge `locale` e `translations` alle props (oltre a un flag interno `enableI18n`). Se la funzione interna restituisce un `redirect` o `notFound`, il risultato viene inoltrato così com&#39;è, senza caricare le traduzioni.

***

## Passaggio 6: aggiungi GTProvider alla tua app

Il componente **`GTProvider`** consente a tutta l&#39;app di accedere alle traduzioni. In `_app.tsx`, estrai le props iniettate da `pageProps` e passale al provider. Il tipo **`WithGTServerSideProps`** descrive la struttura dei dati iniettati:

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import { GTProvider, WithGTServerSideProps } from 'gt-next';

export default function App({
  Component,
  pageProps,
}: AppProps<WithGTServerSideProps>) {
  const { locale, translations, ...restPageProps } = pageProps;

  return (
    <GTProvider locale={locale} translations={translations}>
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

Poiché l&#39;impostazione regionale e le traduzioni arrivano con la risposta del server, il contenuto è già nella lingua dell&#39;utente fin dal primo rendering — senza stato di caricamento lato client.

***

## Passaggio 7: Contrassegna il contenuto per la traduzione

Ora, racchiudi il testo che vuoi tradurre con il componente **`<T>`**. `<T>` sta per &quot;translate&quot;:

```tsx title="pages/index.tsx"
import { T } from 'gt-next';

export default function Home() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

Puoi racchiudere all&#39;interno di `<T>` tutto il JSX che vuoi, in maggiore o minore quantità. Tutto ciò che contiene — testo, elementi annidati, persino la formattazione — viene tradotto come un&#39;unica unità.

***

## Passaggio 8: Aggiungi un selettore di lingua

Inserisci un **`<LocaleSelector>`** in modo che gli utenti possano cambiare lingua:

```tsx title="pages/index.tsx"
import { T, LocaleSelector } from 'gt-next';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

`LocaleSelector` mostra un menu a discesa popolato con le lingue del tuo `gt.config.json`. Quando l&#39;utente seleziona una lingua, `gt-next` salva la scelta nel cookie `generaltranslation.locale` e ricarica la pagina, in modo che il server esegua nuovamente il rendering di tutto nella nuova impostazione regionale.

***

## Passaggio 9: Configura le variabili d&#39;ambiente (facoltativo)

Per vedere le traduzioni durante lo sviluppo, ti servono le chiavi API di General Translation. Queste abilitano la **traduzione su richiesta**: la tua app traduce i contenuti in tempo reale mentre sviluppi.

Crea un file **`.env.local`**:

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

Ottieni gratuitamente le tue chiavi su [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) oppure eseguendo:

```bash
npx gt auth
```

<Callout type="warn">
  Per lo sviluppo, usa una chiave che inizi con `gtx-dev-`. Le chiavi di produzione (`gtx-api-`) sono solo per CI/CD.

  Non esporre mai `GT_API_KEY` nel browser e non salvarla nel controllo versione.
</Callout>

***

## Passaggio 10: Vederlo all&#39;opera

Avvia il server di sviluppo:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

Apri [http://localhost:3000](http://localhost:3000) e usa il menu a discesa della lingua per cambiare lingua. Dovresti vedere i contenuti tradotti.

<Callout type="info">
  In sviluppo, le traduzioni avvengono on-demand: la prima volta che passi a una nuova lingua potresti vedere un breve caricamento. In produzione, le traduzioni vengono pregenerate e caricate istantaneamente.
</Callout>

***

## Passaggio 11: Tradurre le stringhe (non solo JSX)

Per le stringhe semplici — come gli attributi `placeholder`, i valori `aria-label` o il testo `alt` — usa l&#39;hook **`useGT`**:

```tsx title="pages/contact.tsx"
import { useGT } from 'gt-next';

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

***

## Passaggio 12: Distribuisci in produzione

In produzione, le traduzioni vengono generate in fase di build (senza chiamate API in tempo reale). Aggiungi il comando translate allo script di build:

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

Imposta le variabili d&#39;ambiente di **produzione** sul tuo provider di hosting (Vercel, Netlify, ecc.):

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  Le chiavi di produzione iniziano con `gtx-api-` (non `gtx-dev-`). Puoi ottenerne una da [dash.generaltranslation.com](https://dash.generaltranslation.com). Non anteporre mai il prefisso `NEXT_PUBLIC_`.
</Callout>

Ecco fatto: la tua app ora è multilingue. 🎉

***

## Risoluzione dei problemi

<Accordions>
  <Accordion title="Devo usare withGTServerSideProps in ogni pagina?">
    Sì — `<GTProvider>` richiede le props `locale` e `translations`, che esistono solo nelle pagine in cui `getServerSideProps` è wrappato. Per le pagine che non recuperano dati propri, esporta la versione senza argomenti:

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="Posso usare getStaticProps invece?">
    No. La risoluzione dell&#39;impostazione regionale richiede dati per richiesta (il cookie dell&#39;impostazione regionale e l&#39;header `Accept-Language`), che non sono disponibili durante la generazione statica. `gt-next` non fornisce alcun helper `getStaticProps` per il Pages Router.
  </Accordion>

  <Accordion title="La lingua non cambia quando uso il menu a tendina">
    `gt-next` memorizza la preferenza della lingua dell&#39;utente in un cookie chiamato `generaltranslation.locale`. Se in precedenza hai testato con una lingua diversa, questo cookie potrebbe sovrascrivere la tua selezione. Cancella i cookie e riprova.

    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
  </Accordion>

  <Accordion title="Le traduzioni sono lente in sviluppo">
    È normale. In sviluppo, le traduzioni avvengono on-demand (i contenuti vengono tradotti in tempo reale tramite l&#39;API). Questo ritardo **non esiste in Production** — tutte le traduzioni vengono generate in anticipo da `npx gt translate`.
  </Accordion>
</Accordions>

***

## Prossimi passaggi

* [**Guida al componente `<T>`**](/docs/next/guides/t) — Scopri variabili, plurali e pattern di traduzione avanzati
* [**Guida alla traduzione delle stringhe**](/docs/next/guides/strings) — Approfondisci `useGT`
* [**Componenti variabili**](/docs/next/guides/variables) — Gestisci il contenuto dinamico con `<Var>`, `<Num>`, `<Currency>` e `<DateTime>`
* [**Pluralizzazione**](/docs/next/api/components/plural) — Gestisci le forme plurali con il componente `<Plural>`
* [**Distribuzione in produzione**](/docs/next/tutorials/quickdeploy) — configurazione CI/CD, caching e ottimizzazione delle prestazioni
* [**Stringhe condivise**](/docs/next/guides/shared-strings) — Traduci il testo in array, oggetti di configurazione e dati condivisi con `msg()`