# gt-next: General Translation Next.js SDK: Static Site Generation URL: https://generaltranslation.com/it/docs/next/guides/ssg.mdx --- title: Static Site Generation description: Esegui il pre-rendering delle pagine internazionalizzate in fase di build per prestazioni ottimali --- ## Panoramica La Static Site Generation (SSG) esegue il pre-rendering delle pagine in fase di build, creando file HTML statici che possono essere serviti direttamente senza elaborazione lato server. Se combinata con l'internazionalizzazione, SSG genera versioni pre-renderizzate per ogni impostazione regionale. **Fai attenzione ai seguenti problemi durante la configurazione di SSG:** * [Compatibilità con la versione di Next.js](#nextjs-version-compatibility) * [Pagine che non vengono generate staticamente](#pages-not-generating-statically) * [errore di runtime in ambiente di produzione: "DYNAMIC_SERVER_USAGE"](#production-runtime-error-dynamic_server_usage) * ["L'esportazione dell'impostazione regionale non essere presente nel modulo di destinazione"](#export-locale-doesnt-exist-in-target-module) * [Le route delle immagini dei metadati (immagini OG) non funzionano con `getLocale()`](#metadata-image-routes-og-images-fail-with-getlocale) *** ## Setup ### Requisiti di setup Per abilitare SSG con GT, sono necessari: 1. **App Router con instradamento tramite middleware** - vedi la [guida al middleware](/docs/next/guides/middleware) 2. **Funzione `getLocale` personalizzata** - per rilevare l'impostazione regionale durante il rendering statico 3. **Disabilitare `getRegion`** - il rilevamento della regione non è supportato durante il rendering statico 4. **Funzione `generateStaticParams`** - per generare parametri statici per ogni impostazione regionale 5. **File di layout all'interno della directory `/[locale]`** - tutti i file di layout (quindi, in genere, `layout.tsx` e `page.tsx`) devono trovarsi sotto la directory `/[locale]` ### Passaggio 1: Configura il middleware Configura il middleware per le richieste dinamiche (consulta la [guida al middleware](/docs/next/guides/middleware)): ```ts // proxy.ts (Next.js 16+) o middleware.ts (Next.js 15 e versioni precedenti) import { createNextMiddleware } from 'gt-next/middleware'; export default createNextMiddleware(); export const config = { matcher: ['/((?!api|static|.*\\..*|_next).*)'], }; ``` ### Passaggio 2: Definisci il rilevamento dell'impostazione regionale e della regione Crea le funzioni `getLocale` e `getRegion` per rilevare l'impostazione regionale e la regione durante il rendering statico: #### Next.js 15.5+ ```ts // getLocale.ts import { locale } from 'next/root-params'; export default async function getLocale() { return await locale(); } ``` #### Next.js 15.1-15.4 ```ts // getLocale.ts import { unstable_rootParams } from 'next/server'; export default async function getLocale() { return (await unstable_rootParams())?.locale; } ``` ### Passaggio 3: Disattiva getRegion Poiché il rilevamento della regione non è supportato durante il rendering statico, devi sovrascrivere la funzione `getRegion` in modo che restituisca una regione fissa. ```ts // getRegion.ts export default async function getRegion() { return undefined; } ``` ### Passaggio 4: Configura generateStaticParams Assicurati di aver configurato [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) per le tue impostazioni regionali. ```tsx title="page.tsx" import { getLocales } from 'gt-next/server'; export async function generateStaticParams() { return getLocales().map((locale) => ({ locale })); } export default async function Page() { ... } ``` ### Passaggio 5: Sposta tutti i file di layout nella directory `/[locale]` Tutti i file devono poter accedere all'impostazione regionale dell'utente tramite il segmento `/[locale]` nell'URL. Pertanto, devono trovarsi all'interno della directory `/[locale]`. Assicurati di spostare il file di layout root in `/[locale]/layout.tsx`. *** ## Configurazione aggiuntiva Se non vuoi avere `getLocale.ts` e `getRegion.ts` nella directory principale, puoi specificare una directory personalizzata nel file `next.config.js`. ```js // next.config.js export default withGTConfig(nextConfig, { getLocalePath: './src/i18n/getLocale.ts', getRegionPath: './src/i18n/getRegion.ts', }); ``` ## Problemi comuni [#common-issues] ### Compatibilità delle versioni di Next.js Nelle versioni precedenti a Next.js 15.1, non è possibile accedere ai parametri del percorso URL durante la generazione statica. Per usare SSG con gt-next, devi aggiornare a Next.js 15.1 o versione successiva. ### Pagine non generate staticamente Se le tue pagine non vengono generate staticamente, assicurati che: * Le funzioni `getLocale` e `getRegion` siano configurate correttamente ### Errore di runtime in ambiente di produzione: "DYNAMIC_SERVER_USAGE" ``` ⨯ [Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.] { digest: 'DYNAMIC_SERVER_USAGE' } ``` Questo errore si verifica quando i file `getLocale` o `getRegion` non esistono oppure non sono configurati correttamente. Verifica di nuovo che il [passaggio 2](#step-2-define-locale-and-region-detection) e il [passaggio 3](#step-3-disable-getregion) siano stati completati. ### "L'esportazione dell'impostazione regionale non essere presente nel modulo di destinazione" ``` ./getLocale.ts:2:1 Export locale doesn't exist in target module 1 | // getLocale.ts > 2 | import { locale } from 'next/root-params'; | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3 | export default async function getLocale() { 4 | return await locale(); 5 | } ``` Questo errore si verifica in genere quando hai un file `layout.tsx`, `page.tsx`, ecc. che non si trova all'interno della directory `/[locale]`. Per risolvere il problema, assicurati che tutti i file dei segmenti di route (in genere `layout.tsx` e `page.tsx`) siano discendenti della directory `/[locale]`. Durante la SSG, l'unico modo per determinare l'impostazione regionale di un utente è tramite il percorso dell'URL. Quindi, se proviamo a eseguire un file `layout.tsx` al di fuori della directory `/[locale]`, verrà generato un errore perché non ha accesso a questo parametro root. L'aspetto poco intuitivo è che, quando viene renderizzata una pagina, vengono renderizzati anche tutti i file `layout.tsx` che la racchiudono. Quindi, potresti aver aggiunto la SSG a un file `page.tsx` che si trova perfettamente all'interno della directory `/[locale]`, ma in realtà l'errore è causato da un file `layout.tsx` che si trova altrove. Sconsigliamo vivamente questa pratica. Tutti i file dei segmenti di route (tranne `not-found.tsx`) devono trovarsi all'interno della directory `/[locale]` quando si usa la SSG. Ma, se è indispensabile, ti serviranno due file di layout root separati: uno all'interno della directory `/[locale]` e uno al di fuori di essa. In questo modo, la SSG eseguirà solo il layout all'interno della directory `/[locale]`. Inoltre, potresti dover modificare il middleware per instradare verso eventuali segmenti presenti al di fuori della directory `/[locale]`, saltando il middleware di localizzazione. ### Le route delle immagini dei metadati (immagini OG) non funzionano con `getLocale()` ``` Error: Route /[locale]/.../opengraph-image used import('next/root-params').locale() inside a Route Handler. ``` Le route delle immagini dei metadati di Next.js (`opengraph-image.tsx`, `twitter-image.tsx`) sono internamente dei Route Handler e `next/root-params` non è supportato nei Route Handler. Ciò significa che `getLocale()`, `getMessages()` e `getGT()` daranno errore in questi contesti. **Correzione:** usa `registerLocale()` per impostare esplicitamente l'impostazione regionale all'inizio dell'handler: ```tsx title="app/[locale]/opengraph-image.tsx" import { ImageResponse } from 'next/og'; import { registerLocale, getMessages, msg } from 'gt-next/server'; const HEADING = msg('Welcome to our site'); export default async function OGImage({ params, }: { params: Promise<{ locale: string }>; }) { const { locale } = await params; registerLocale(locale); const m = await getMessages(); return new ImageResponse( (
{m(HEADING)}
), { width: 1200, height: 630 } ); } ``` Questo vale anche per `twitter-image.tsx` e per qualsiasi altra route delle immagini dei metadati. *** ## Per approfondire **Guardalo in azione:** Consulta l'[app di esempio per la Static Site Generation](https://github.com/gt-examples/static-site-generation) per una demo funzionante — [anteprima live](https://static-site-generation.generaltranslation.dev). * Consulta la [guida al middleware](/docs/next/guides/middleware), necessaria per il routing in base all'impostazione regionale * Consulta le [note di rilascio](/devlog/gt-next_v6_10_0) per migrare dal pattern SSG legacy * Vedi un'app di esempio nel monorepo [qui](https://github.com/generaltranslation/gt/tree/main/examples/next-ssg)