Panoramica

Questo comportamento è attualmente deprecato; vedi gt-next@6.10.0 per il nuovo comportamento.

Il rendering statico è una funzionalità centrale del framework Next.js: genera pagine prerenderizzate in fase di build, per prestazioni e SEO ottimali. Di conseguenza, qualsiasi libreria nativa per Next.js dovrebbe integrarsi perfettamente con questo modello di rendering. gt-next 6.9.0 introduce il supporto al rendering statico, consentendo alle applicazioni internazionalizzate di sfruttare appieno le capacità di generazione statica di Next.js senza compromettere il rilevamento dell'impostazione regionale né le funzionalità di traduzione.

Che cos'è il rendering statico?

Il rendering statico genera HTML in fase di build anziché a ogni richiesta. Sebbene questo approccio offra prestazioni eccezionali, pone delle sfide per le librerie di i18n, che in genere si basano su header delle richieste, cookie o middleware per determinare l'impostazione regionale dell'utente. Durante il rendering statico, queste dipendenze disponibili solo al momento della richiesta non sono accessibili, perciò sono necessari approcci alternativi per rilevare l'impostazione regionale.

Configurazione del rendering statico

Prima di configurare gt-next, assicurati che la tua applicazione Next.js sia configurata per la generazione statica seguendo la documentazione di generateStaticParams.

La configurazione prevede tre componenti chiave:

1. Abilita il rendering statico nella configurazione

export default withGTConfig(nextConfig, {
  experimentalEnableSSG: true,
})

2. Configura il middleware

Imposta il middleware per le richieste dinamiche:

// 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).*)",
  ],
}

3. Definisci il rilevamento statico dell'impostazione regionale

Crea una funzione getStaticLocale che determini l'impostazione regionale durante il rendering statico. Questa funzione viene eseguita solo durante la generazione statica; durante l'SSR si usa il comportamento predefinito (lettura di header, cookie, ecc.).

Next.js 15.5+

// getStaticLocale.ts
import { locale } from "next/root-params";

export default async function getStaticLocale() {
  return await locale();
}

Next.js 15.1-15.4

// getStaticLocale.ts  
import { unstable_rootParams } from "next/server";

export default async function getStaticLocale() {
  return (await unstable_rootParams())?.locale;
}

getStaticRegion può essere utilizzato per personalizzare il rilevamento della regione durante il rendering statico.

Vantaggi

Nativo di Next.js: Sfrutta il sistema di root params integrato di Next.js per essere compatibile con il rendering statico.

Funzionalità aggiuntive

Oltre alla generazione statica, questa release introduce anche il supporto per funzioni getLocale() e getRegion() personalizzate, configurabili sia per gli ambienti SSR sia per quelli con rendering statico.