Come implementare l'internazionalizzazione in un'applicazione Next.js che utilizza il Pages Router

Man mano che il mondo si globalizza, è sempre più importante che gli sviluppatori web creino applicazioni in grado di soddisfare utenti di diversi paesi e culture. Uno dei modi principali per ottenere questo è attraverso l'internazionalizzazione (i18n), che permette di adattare la tua applicazione a lingue, valute e formati di data diversi.

In questo tutorial, esploreremo come aggiungere l'internazionalizzazione alla tua applicazione React Next.js, con rendering lato server. TL;DR: Vedi l'esempio completo qui.

Questa guida è per applicazioni Next.js che utilizzano il Pages Router.
Se stai usando il App Router, consulta invece questa guida.

Passaggio 1: Installa una libreria i18n

Per implementare l'internazionalizzazione nella tua applicazione Next.js, prima sceglieremo una libreria i18n. Ci sono diverse librerie popolari, tra cui next-intl. Tuttavia, in questo esempio useremo TacoTranslate.

TacoTranslate traduce automaticamente le tue stringhe in qualsiasi lingua usando IA all'avanguardia e ti libera dalla tediosa gestione dei file JSON.

Installiamolo usando npm nel tuo terminale:

npm install tacotranslate

Passo 2: Crea un account gratuito su TacoTranslate

Ora che hai installato il modulo, è il momento di creare il tuo account TacoTranslate, un progetto di traduzione e le chiavi API associate. Crea un account qui. È gratuito e non richiede l'inserimento di una carta di credito.

Nell'interfaccia utente dell'applicazione TacoTranslate, crea un progetto e vai alla scheda delle chiavi API. Crea una chiave read e una chiave read/write. Le salveremo come variabili d'ambiente. La chiave read è quella che chiamiamo public e la chiave read/write è secret. Ad esempio, potresti aggiungerle a un file .env nella root del tuo progetto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assicurati di non esporre mai la chiave API segreta read/write negli ambienti di produzione lato client.

Aggiungeremo anche due ulteriori variabili d'ambiente: TACOTRANSLATE_DEFAULT_LOCALE e TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Il codice della locale di fallback predefinita. In questo esempio lo impostiamo su en per l'inglese.
• TACOTRANSLATE_ORIGIN: La “cartella” in cui verranno memorizzate le tue stringhe, ad esempio l'URL del tuo sito web. Per saperne di più sulle origini, leggi qui.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Passaggio 3: Configurazione di TacoTranslate

Per integrare TacoTranslate con la tua applicazione, dovrai creare un client usando le chiavi API ottenute in precedenza. Ad esempio, crea un file chiamato /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY ??
		'',
	projectLocale: process.env.TACOTRANSLATE_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Definiremo automaticamente TACOTRANSLATE_API_KEY a breve.

Creare il client in un file separato rende più semplice riutilizzarlo in seguito. Ora, utilizzando un file personalizzato /pages/_app.tsx, aggiungeremo il provider TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Se hai già dei pageProps e _app.tsx personalizzati, estendi la definizione con le proprietà e il codice di cui sopra.

Passo 4: Implementazione del rendering lato server

TacoTranslate consente il rendering lato server delle tue traduzioni. Questo migliora notevolmente l'esperienza utente mostrando immediatamente il contenuto tradotto, invece di mostrare prima un lampo di contenuto non tradotto. Inoltre, possiamo evitare richieste di rete dal client, perché abbiamo già tutte le traduzioni necessarie.

Inizieremo creando o modificando /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		client: tacoTranslateClient,
		isProduction:
			process.env.TACOTRANSLATE_ENV === 'production' ||
			process.env.VERCEL_ENV === 'production' ||
			(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
				process.env.NODE_ENV === 'production'),
	});
};

Modifica il controllo isProduction per adattarlo alla tua configurazione. Se true, TacoTranslate renderà disponibile la chiave API pubblica. Se ci troviamo in un ambiente locale, di test o di staging (isProduction is false), useremo la chiave API segreta read/write per assicurarci che le nuove stringhe vengano inviate per la traduzione.

Finora abbiamo configurato l'applicazione Next.js solo con un elenco di lingue supportate. La prossima cosa che faremo è recuperare le traduzioni per tutte le tue pagine. Per farlo, utilizzerai o getTacoTranslateStaticProps o getTacoTranslateServerSideProps, a seconda delle tue esigenze.

Queste funzioni accettano tre argomenti: un oggetto Next.js Static Props Context, la configurazione per TacoTranslate e proprietà opzionali di Next.js. Nota che revalidate su getTacoTranslateStaticProps è impostato su 60 per impostazione predefinita, in modo che le tue traduzioni rimangano aggiornate.

Per usare una delle due funzioni in una pagina, supponiamo che tu abbia un file di pagina come /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Ora dovresti poter utilizzare il componente Translate per tradurre le stringhe in tutti i tuoi componenti React.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Passaggio 5: Distribuisci e testa!

Abbiamo finito! La tua applicazione React verrà ora tradotta automaticamente quando aggiungi qualsiasi stringa a un componente Translate. Nota che solo gli ambienti con permessi read/write sulla chiave API potranno creare nuove stringhe da tradurre. Consigliamo di avere un ambiente di staging chiuso e protetto dove puoi testare la tua applicazione di produzione con una chiave API di questo tipo, aggiungendo nuove stringhe prima di andare in produzione. Questo impedirà a chiunque chiunque di rubare la tua chiave API segreta, e potenzialmente di gonfiare il tuo progetto di traduzione aggiungendo nuove stringhe non correlate.

Assicurati di consultare l'esempio completo sul nostro profilo GitHub. Lì troverai anche un esempio di come farlo usando App Router! Se incontri problemi, non esitare a contattarci, e saremo più che felici di aiutarti.

TacoTranslate ti permette di localizzare automaticamente le tue applicazioni React, rapidamente, da e verso oltre 75 lingue. Inizia oggi!