# 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 Docs index: https://generaltranslation.com/llms.txt Description: Aggiungi più lingue a un'app Next.js Pages Router con General Translation 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 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** (Next.js 13.0.0 o versione successiva, esclusi 15.2.1 e 15.2.2) * 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 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.