Next.js supporta il routing multilingua di default. Allo stesso tempo, non offre un sistema per gestire la traduzione dei contenuti. Tutto ciò che fa è leggere il “locale” contenuto nell’URL di una pagina e mostrare all’utente la lingua corretta di conseguenza. Per creare un sito internazionale in Next.js è necessario gestire manualmente le traduzioni, operazione macchinosa e banale. Per fortuna esiste next-i18next, una libreria Next.js per il 18n che rende il processo di localizzazione più agevole e intuitivo.
Alla fine di questo tutorial, saprete come utilizzare l’i18n in Next.js. Non perdiamo altro tempo e iniziamo!
Cosa è next-i18next?
next-i18next è un framework per la localizzazione dei contenuti in applicazioni Next.js. Nel dettaglio, offre un modo semplice per gestire l’internazionalizzazione e la localizzazione. Per utilizzarlo, tutto ciò che devi fare è configurarlo e iniziare ad aggiungere le tue traduzioni in specifici file JSON. La libreria si occuperà di tutto il resto.
Il framework è basato su i18next e react-i18next, due tra le più popolare librerie di i18n per JavaScript e React, rispettivamente. In particolare, next-i18next aggiunge il supporto per il rendering lato server (SSR), la generazione di siti statici (SSG) e la rigenerazione statica incrementale (ISR). Nel caso in cui stessi utilizzando Next.js 13 con la directory app, non è necessario next-i18next. In questo scenario, è possibile utilizzare direttamente i18next e react-i18next, come spiegato nella guida citata nella documentazione.
Con next-i18next, puoi costruire un sito Next.js che supporta più lingue senza alcuno sforzo. Provalo nella demo sul sito ufficiale!
Perché next-i18next è meglio di altre librerie i18n?
Sono disponibili diverse librerie per l’i18n in Next.js. Ad esempio, react-intl è una delle più popolari, con milioni di download settimanali. Tuttavia, nessuna di esse è facile da usare, richiede poca configurazione e offre tante funzionalità quanto next-i18next. Questo è ciò che la rende la migliore libreria i18n per Next.js.
Integrare next-i18next in un’applicazione Next.js richiede pochissimi passaggi. Configurarlo è ancora più semplice. Fatto ciò, puoi iniziare a passare le traduzioni ai componenti di pagina attraverso le props tramite getServerSideProps() o getStaticProps(). Questo ti permette di complementare le funzionalità di routing multilingua offerte da Next.js, fornendoti tutto il necessario per gestire contenuti localizzati.
Ecco alcune feature chiave supportate da next-i18next:
- Supporto per il SSR e il SSG
- Componenti e hook per tradurre i vostri componenti React
- Traduzioni salvate in file JSON e non nei componenti
- Sistema di cambio della lingua corrente personalizzabile
- Supporto per i placeholder, i plurali e i namespace di
i18next - Rilevamento automatico del locale in base alla lingua del browser dell’utente
Nel complesso, next-i18next è un framework per l’i18n potente e flessibile. È tempo di imparare a usarlo nella costruzione di un sito Next.js multilingua!
Lettura consigliata: Come ottimizzare Next.js per andare in produzione
Come configurare next-i18next
Segui i ogni passo e impara a integrare next-i18next in una applicazione Next.js.
Prerequisiti
Per poter seguire questo tutorial, occorre innanzitutto un’applicazione Next.js da localizzare. Se preferisci partire da zero, può inizializzare un progetto Next.js con:
npx create-next-app@latestCode language: CSS (css)Rispondi a tutte le domande, attendi che l’installazione delle dipendenze termini ed esegui il comando seguente per lanciare il server di sviluppo:
npm run dev
Se il processo di inizializzazione è terminato come previsto, dovresti vedere la pagina predefinita Create Next App qui sotto:
Fantastico! Ora hai un progetto pronto per essere trasformato in un sito multilingua in Next.js!
Installa next-i18next
Aggiungi next-i18next alle dipendenze del progetto con:
npm install next-i18next react-i18next i18next
Nota che il comando di installazione coinvolge anche react-i18next e i18next. Ciò è necessario perché queste due librerie sono dipendenze peer di next-i18next. In altre parole, next-i18next non funzionerebbe senza di esse.
Configura la tua app Next.js
Crea un file next-i18next.config.js nella cartella root del tuo progetto. Questo altro non è che il file di configurazione richiesto da next-i18next. Inizializzalo come segue:
// next-i18next.config.js
module.exports = {
i18n: {
// i locali supportati dall'applicazione
locales: ['en', 'it', 'es'],
// il locale predefinito da usare quando si visita
// un percorso non localizzato (per esempio `/about`)
defaultLocale: 'en'
},
}Code language: JavaScript (javascript)Il file deve obbligatoriamente esportare un oggetto i18n, la cui struttura è definita nella documentazione di Next.js. Nello specifico, deve includere un array locales con le lingue supportate dal sito e una variabile defaultLocale contenente uno dei locali inclusi nell’array. Nota che i locali devono essere specificati utilizzando i loro identificatori UTS.
Per abilitare la funzione di routing multilingua di Next.js passa l’oggetto i18n al filenext.config.js:
// next.config.js
const { i18n } = require('./next-i18next.config')
const nextConfig = {
i18n,
reactStrictMode: true,
}
module.exports = nextConfigCode language: JavaScript (javascript)Infine, aggiorna il file src/pages/_app.js come segue:
// src/pages/_app.js
import { appWithTranslation } from 'next-i18next'
const App = ({ Component, pageProps }) => (
<Component {...pageProps} />
)
export default appWithTranslation(App)Code language: JavaScript (javascript)Come puoi vedere, è necessario wrappare il componente main App con appWithTranslation(). Questa funzione è in realtà un componente HOC (High-Order Component) di React. In dettaglio, si occupa di abilitare a livello globale le funzionalità i18n esposte da next-i18next nella tua app Next.js.
Ottimo! Il tuo sito multilingua Next.js è ora pronto ad accettare contenuti localizzati.
Struttura il tuo progetto
next-i18next si aspetta che i file JSON con le traduzioni siano organizzati nella cartella public in questo modo:
public
└── locales
├── en
| └── common.json
├── es
| └── common.json
└── it
└── common.jsonCode language: PHP (php)Puoi customizzare questo comportamento predefinito impostando i valori localePath e localeStructure nel file next-i18next.config.js.
Così è come si presenta ora il tuo progetto Next.js:
La cartella locales in public è strutturata come richiesto e contiene i file common.json, che al momento sono vuoti.
Definisci una pagina localizzata
È ora giunto il momento di costruire una pagina Next.js con contenuti multilingua. Modifica la home page del tuo sito aggiornando il file src/pages/index.js:
// src/pages/index.js
import { serverSideTranslations } from 'next-i18next/serverSideTranslations'
import { useTranslation } from 'next-i18next'
export default function Home() {
const { t } = useTranslation()
return (
<>
<h1>{t("HELLO_WORLD")}</h1>
</>
)
}
export async function getStaticProps(context) {
// estrae l'identificatore UTS del locale dall'URL
const { locale } = context
return {
props: {
// passa le props con le traduzioni al componente di pagina
...(await serverSideTranslations(locale)),
},
}
}Code language: JavaScript (javascript)Capiamo ora come funziona questo componente, un passo alla volta.
La funzione getStaticProps() di Next.js si occupa di definire la strategia di rendering della pagina. Come spiegato nella documentazione ufficiale, è possibile recuperare il locale estratto dall’URL della pagina tramite il parametro context.
Gli URL /, /es e /it mandano tutti alla home page, ma:
- In
/,localeèenperchèdefaultLocaleèen - In
/es,localeèes - In
/it,localeèit
Dovrebbe ora essere chiaro come funziona la feature di routing multilingua di Next.js.
Successivamente, l’HOC serverSideTranslations() di next-i18next prende locale come parametro e genera le configurazioni di traduzione, passate come props al componente di pagina. Tieni a mente che, in ogni pagina da localizzare, devi passare il risultato di questa funzione alle props.
Nota che la logica descritta qui sopra rimane uguale sia nel caso di getStaticProps() che di getServerSideProps().
Il componente di pagina o qualsiasi altro componente sotto il suo albero può ora usare l’hook useTranslation() di next-i18next. Come sottolineato nella documentazione, stai attento a non importare useTranslation() da react-i18next!
Questo hook restituisce la funzione t, la quale accetta una stringa come parametro e la usa come chiave per trovare la corrispondente traduzione dal file common.json corretto. Se non vengono trovate traduzioni corrispondenti, restituisce la stringa chiave.
Verifica che ciò è vero lanciando il server di sviluppo con:
npm run devApri http://localhost:3000 nel browser.
Poiché tutti i file common.json sono vuoti, indipendentemente dalla pagina visitata, sia questa /, /es o /it, vedrai sempre:
Tempo di definire qualche traduzione!
Traduci il tuo contenuto
Nei file common.json, aggiungi la chiave HELLO_WORLD con i seguenti valori:
/en/common.json:
{
"HELLO_WORLD": "Hello, World!"
}Code language: JSON / JSON with Comments (json)/es/common.json:
{
"HELLO_WORLD": "¡Hola, mundo!"
}Code language: JSON / JSON with Comments (json)/it/common.json:
{
"HELLO_WORLD": "Ciao, mondo!"
}Code language: JSON / JSON with Comments (json)Non dimenticare che ogni volta che modifichi qualcosa nella cartella public, devi poi riavviare il server di sviluppo. Killa l’istanza corrente e riavviarla.
Metti tutto insieme
Se apri le tre versioni localizzate della home page del tuo sito Next.js nel browser, vedrai:
http://localhost:3000/:
http://localhost:3000/es:
http://localhost:3000/it:
Et voilà! Hai appena imparato a costruire un sito internazionale in Next.js!
Puoi trovare il codice dell’applicazione di esempio sviluppata qui nella repository GitHub che supporta l’articolo. Clonate la repo e lancia il sito in locale con:
git clone https://github.com/Tonel/i18n-next-demo
cd i18n-next-demo
npm i
npm run devCode language: PHP (php)Visita http://localhost:3000 and ammira l’app localizzata di demo!
Conclusioni
In questo articolo abbiamo visto come creare un sito multilingua in Next.js. Con l’aiuto di next-i18next, è possibile implementare facilmente l’i18n in Next.js, rendendo più semplice l’integrazione di contenuti localizzati in un sito.
Per prima cosa, hai capito quali sono le funzionalità di i18n offerte nativamente da Next.js e perché è necessaria una dipendenza aggiuntiva per gestire la logica di traduzione. Hai appreso perché next-i18next è la migliore libreria i18n per Next.js e come configurarla in un tutorial passo dopo passo. Costruire un sito localizzato in Next.js non è mai stato così facile!
Grazie per aver letto questo articolo! Speriamo che ti sia stato utile!
