Panoramica

Il rendering statico è una caratteristica fondamentale del framework Next.js, che fornisce pagine pre-renderizzate in fase di build per prestazioni e SEO ottimali. Dato questo, qualsiasi libreria nativa di Next.js dovrebbe funzionare in modo trasparente all'interno di questo modello di rendering. gt-next 6.9.0 introduce il supporto per il rendering statico, consentendo alle applicazioni internazionalizzate di sfruttare appieno le funzionalità di generazione statica di Next.js senza compromettere il rilevamento della lingua o 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, presenta delle sfide per le librerie di i18n che in genere si basano sugli header della richiesta, sui cookie o sul middleware per determinare la lingua dell'utente. Durante il rendering statico, queste dipendenze disponibili solo al momento della richiesta non sono accessibili, e sono quindi necessari approcci alternativi per il rilevamento della lingua.

Configurazione del rendering statico

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

La configurazione prevede tre componenti principali:

1. Abilita il rendering statico nella configurazione

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

2. Configurare il middleware

Configura il middleware per le richieste dinamiche:

// proxy.ts (Next.js 16+) o middleware.ts (Next.js 15 e inferiori)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

3. Definire il rilevamento della locale in fase statica

Crea una funzione getStaticLocale che determina la locale durante il rendering statico. Questa funzione viene eseguita solo durante la generazione statica: durante l'SSR viene utilizzato 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;
}

È possibile chiamare getStaticRegion per personalizzare il rilevamento della regione durante il rendering statico.

Vantaggi

Nativo in Next.js: sfrutta il sistema integrato di root params di Next.js per garantire la compatibilità con il rendering statico.

Funzionalità aggiuntive

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