# General Translation React SDKs (gt-react, gt-next): Next.js Pages Router guida rapida
URL: https://generaltranslation.com/it/docs/react/nextjs-pages-router-quickstart.mdx
---

title: Next.js Pages Router guida rapida
description: Aggiungi più lingue a un'app Next.js Pages Router con General Translation in meno di 10 minuti.
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

# Guida rapida a Next.js Pages Router

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

Nel 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 entrambi a un `<GTProvider>` in `_app.tsx`, così il primo rendering è già tradotto.

L&#39;entry `gt-next/server` è solo per l&#39;App Router e non funziona con il Pages Router.

**Prerequisiti:**

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

<Callout type="info">
  **Nota:** Se usi l&#39;App Router, segui invece la [guida rapida a Next.js App Router](/docs/react/nextjs-quickstart). Usa i componenti server e non richiede alcuna configurazione di `getServerSideProps`.
</Callout>

## guida rapida [#quickstart]

### 1. Installa i pacchetti

`gt-next` è la libreria che gestisce le traduzioni nella tua app. `gt` è lo strumento CLI che prepara le traduzioni per la 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>

### 2. Configura la tua configurazione di Next.js

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

```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. Per gli URL con prefisso dell&#39;impostazione regionale, segui la [guida al middleware del Pages Router](/docs/react/nextjs/pages-router-middleware).

### 3. Crea un file di configurazione per le traduzioni

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

```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/dashboard/reference/supported-locales).
* **`files.gt.output`** — dove la CLI salva i file di traduzione. `[locale]` viene sostituito con il codice di ciascuna lingua (ad esempio, `public/_gt/es.json`).

Aggiungi `public/_gt/` al tuo **`.gitignore`** — questi file vengono generati, non scritti manualmente:

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

### 4. Aggiungi una funzione di caricamento per le traduzioni locali

Crea un file **`loadTranslations`** nella radice del progetto (o nella directory `src/`). Questo indica a `gt-next` 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">
  **Nota:** Le traduzioni locali sono incluse nel bundle della tua app, quindi si caricano istantaneamente senza dipendere da servizi esterni. Per dettagli e compromessi, vedi [Memorizzazione delle traduzioni](/docs/react/guides/storing-translations).
</Callout>

### 5. Avvolgi getServerSideProps nelle pagine

Avvolgi il `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 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 ha bisogno di props lato server specifiche, chiamala senza argomenti:

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

export const getServerSideProps = withGTServerSideProps();
```

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

### 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’impostazione regionale e le traduzioni arrivano con la risposta del server, il primo rendering è già nella lingua dell&#39;utente — senza alcuno stato di caricamento lato client.

### 7. Contrassegna i contenuti da tradurre

Ora, racchiudi nel componente **`<T>`** qualsiasi testo che vuoi tradurre. `<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>` tanto o poco JSX quanto vuoi. Tutto ciò che c&#39;è al suo interno — testo, elementi annidati, persino la formattazione — viene tradotto come un&#39;unica unità.

### 8. Aggiungi un selettore di lingua

Inserisci un **`<LocaleSelector>`** così gli utenti possono 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` esegue il rendering di un menu a discesa compilato con le lingue del tuo `gt.config.json`. Quando l’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.

### 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 lavori.

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

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

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

```bash
npx gt auth
```

<Callout type="warn">
  **Avviso:** 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 inserirla mai nel sistema di controllo versione.
</Callout>

### 10. Guarda come funziona

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">
  **Nota:** In sviluppo, le traduzioni avvengono on-demand, quindi la prima volta che passi a una nuova lingua potresti vedere brevemente uno stato di caricamento. In produzione, le traduzioni vengono pre-generate e si caricano istantaneamente.
</Callout>

### 11. Traduci le stringhe (non solo JSX)

Per le stringhe di testo 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>
  );
}
```

### 12. Distribuisci in produzione

In produzione, le traduzioni sono pregenerate 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">
  **Avviso:** Le chiavi di produzione iniziano con `gtx-api-` (non `gtx-dev-`). Puoi ottenerne una da [dash.generaltranslation.com](https://dash.generaltranslation.com). Non aggiungere mai il prefisso `NEXT_PUBLIC_`.
</Callout>

Ecco fatto: la tua app ora è multilingue. 🎉

## Risoluzione dei problemi [#troubleshooting]

<Accordions>
  <Accordion title="Devo usare withGTServerSideProps in ogni pagina?">
    Sì — `<GTProvider>` richiede le props `locale` e `translations`, che esistono solo nelle pagine il cui `getServerSideProps` è stato 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 al suo posto?">
    Sì. Wrappa la pagina con `withGTStaticProps` e continua a passare le props generate a `GTProvider` in `_app.tsx`. Per la configurazione completa, consulta la [guida alla generazione statica del sito con Pages Router](/docs/react/nextjs/pages-router-static-site-generation).
  </Accordion>

  <Accordion title="La lingua non cambia quando uso il menu a discesa">
    `gt-next` memorizza la preferenza della lingua dell&#39;utente in un cookie chiamato `generaltranslation.locale`. Se in precedenza hai effettuato test con una lingua diversa, questo cookie potrebbe sovrascrivere la 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 si verifica in produzione**: tutte le traduzioni sono pre-generate da `npx gt translate`.
  </Accordion>
</Accordions>
## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables