# General Translation React SDKs (gt-react, gt-next, gt-react-native): Guida rapida a Next.js Pages Router URL: https://generaltranslation.com/it/docs/react/nextjs-pages-router-quickstart.mdx --- title: Guida rapida a Next.js Pages Router 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 --- 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'impostazione regionale dell'utente, carica uno snapshot delle traduzioni e li passa entrambi a un [``](/docs/react/reference/components/gt-provider) in `_app.tsx`, così il primo rendering è già tradotto. L'entry `gt-next/server` è solo per l'App Router e non funziona con il Pages Router. **Prerequisiti:** * Un'app Next.js che usa il **Pages Router** * Node.js 18+ **Nota:** Se usi l'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`. ## 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. ```bash npm i gt-next npm i -D gt ``` ```bash yarn add gt-next yarn add --dev gt ``` ```bash bun add gt-next bun add --dev gt ``` ```bash pnpm add gt-next pnpm add --save-dev gt ``` ### 2. 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": ["en", "es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` * **`defaultLocale`** — la lingua in cui è scritta la tua app (la lingua sorgente). * **`locales`** — ogni impostazione regionale disponibile nella tua app. Includi `defaultLocale` perché il routing internazionalizzato di Next.js lo richiede, quindi aggiungi le lingue in cui vuoi tradurre. Scegline una dall'[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/ ``` ### 3. Configura il routing internazionalizzato di Next.js Il Pages Router utilizza il [routing internazionalizzato di Next.js](https://nextjs.org/docs/pages/guides/internationalization) per gli URL con prefisso dell'impostazione regionale e il rilevamento dell'impostazione regionale della richiesta. Importa le impostazioni regionali in `next.config.ts`, quindi avvolgi la configurazione con `withGTConfig`: ```ts title="next.config.ts" import type { NextConfig } from 'next'; import { withGTConfig } from 'gt-next/config'; import gtConfig from './gt.config.json'; const nextConfig: NextConfig = { i18n: { locales: gtConfig.locales, defaultLocale: gtConfig.defaultLocale, }, }; export default withGTConfig(nextConfig); ``` Next.js mantiene l'impostazione regionale predefinita in `/` e aggiunge un prefisso alle altre impostazioni regionali, come `/es` e `/fr`. Non ti servono né il middleware `gt-next` né un segmento di route `pages/[locale]`. Per i dettagli sul rilevamento e sulla migrazione, consulta [routing delle impostazioni regionali con Pages Router](/docs/react/nextjs/pages-router-middleware). ### 4. Aggiungi una funzione di caricamento per le traduzioni locali Crea un file **[`loadTranslations`](/docs/react/reference/functions/load-translations)** 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 {}; } } ``` **Nota:** Questi file di traduzione non esistono finché non li crei con [`npx gt generate`](/docs/cli/reference/commands/generate) (non è necessaria alcuna chiave API) oppure con [`npx gt translate`](/docs/cli/reference/commands/translate) (con credenziali). Fino ad allora, il bundler segnala la mancanza della directory `public/_gt` e il `try`/`catch` qui sopra restituisce `{}`, così l'app continua comunque a funzionare con contenuti non tradotti. `withGTConfig` rileva automaticamente un file `loadTranslations.[js|ts]` nella radice del progetto o nella directory `src/` — non serve alcuna configurazione aggiuntiva. **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). ### 5. Avvolgi getServerSideProps nelle pagine Avvolgi il `getServerSideProps` di ogni pagina con **`withGTServerSideProps`**. A ogni richiesta, legge l'impostazione regionale che Next.js ha determinato in `context.locale`, carica uno snapshot delle traduzioni per quell'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'è, senza caricare le traduzioni. ### 6. Aggiungi GTProvider alla tua app Il componente **[`GTProvider`](/docs/react/reference/components/gt-provider)** consente a tutta l'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 Router from 'next/router'; import { GTProvider, type WithGTServerSideProps } from 'gt-next'; export default function App({ Component, pageProps, }: AppProps) { const { locale, translations } = pageProps; return ( { void Router.push(Router.pathname, Router.asPath, { locale: nextLocale, }); }} > ); } ``` Poiché l’impostazione regionale e le traduzioni arrivano con la risposta del server, il primo rendering è già nella lingua dell'utente — senza alcuno stato di caricamento lato client. Il callback `_reload` passa le modifiche dell’impostazione regionale al router di Next.js, affinché carichi le props della pagina per l’impostazione regionale selezionata. ### 7. Contrassegna i contenuti da tradurre Ora, racchiudi nel componente **[``](/docs/react/reference/components/t)** qualsiasi testo che vuoi tradurre. [``](/docs/react/reference/components/t) sta per "translate": ```tsx title="pages/index.tsx" import { T } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` Puoi racchiudere all'interno di [``](/docs/react/reference/components/t) tanto o poco JSX quanto vuoi. Tutto ciò che c'è al suo interno — testo, elementi annidati, persino la formattazione — viene tradotto come un'unica unità. ### 8. Aggiungi un selettore di lingua Inserisci un **[``](/docs/react/reference/components/locale-selector)** così gli utenti possono cambiare lingua: ```tsx title="pages/index.tsx" import { T, LocaleSelector } from 'gt-next'; export default function Home() { return (

Welcome to my app

This content will be translated automatically.
); } ``` [`LocaleSelector`](/docs/react/reference/components/locale-selector) esegue il rendering di un menu a discesa compilato con le lingue del tuo `gt.config.json`. Quando l’utente seleziona una lingua, il callback in `_app.tsx` reindirizza all’URL localizzato e Next.js salva la scelta nel cookie `NEXT_LOCALE`. Il server esegue quindi il rendering dell’impostazione regionale selezionata. ### 9. Configura le variabili d'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/en-US/signin) oppure eseguendo: ```bash npx gt auth ``` **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. ### 10. Guarda come funziona Avvia il server di sviluppo: ```bash npm run dev ``` ```bash yarn dev ``` ```bash bun dev ``` ```bash pnpm dev ``` Apri [http://localhost:3000](http://localhost:3000) e usa il menu a discesa della lingua per cambiare lingua. Dovresti vedere i contenuti tradotti. **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. ### 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'hook **[`useGT`](/docs/react/reference/hooks/use-gt)**: ```tsx title="pages/contact.tsx" import { useGT } from 'gt-next'; export default function ContactPage() { const gt = useGT(); return (
); } ``` ### 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'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 ``` **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_`. Ecco fatto: la tua app ora è multilingue. 🎉 ## Risoluzione dei problemi [#troubleshooting] Sì — [``](/docs/react/reference/components/gt-provider) 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(); ``` Sì. Wrappa la pagina con `withGTStaticProps` e continua a passare le props generate a [`GTProvider`](/docs/react/reference/components/gt-provider) 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). Verifica che `_reload` chiami `Router.push` con l'opzione `locale` selezionata, come mostrato sopra. Dopo la selezione, l'URL dovrebbe usare il prefisso dell'impostazione regionale e il cookie `NEXT_LOCALE` dovrebbe contenere tale impostazione regionale. È normale. In sviluppo, le traduzioni avvengono on-demand (i contenuti vengono tradotti in tempo reale tramite l'API). Questo ritardo **non si verifica in produzione**: tutte le traduzioni sono pre-generate da [`npx gt translate`](/docs/cli/reference/commands/translate). ## Next steps - /docs/react/guides/translating-jsx - /docs/react/guides/translating-strings - /docs/react/guides/managing-locales - /docs/react/guides/formatting-variables