La soluzione migliore per l'internazionalizzazione (i18n) nelle app Next.js

Come funziona

Con l'aumentare della globalizzazione, è sempre più importante che gli sviluppatori web realizzino applicazioni in grado di rivolgersi a utenti provenienti da paesi e culture diverse. Uno dei metodi principali per ottenere ciò è l'internazionalizzazione (i18n), che permette di adattare la tua applicazione a lingue, valute e formati di data differenti.

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 le applicazioni Next.js che utilizzano il Pages Router.
Se utilizzi il App Router, consulta invece questa guida.

Passaggio 1: Installa una libreria i18n

Per implementare l'internazionalizzazione nella tua applicazione Next.js, per prima cosa 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 utilizzando l'intelligenza artificiale all'avanguardia e ti libera dalla tediosa gestione dei file JSON.

Installiamola usando npm nel tuo terminale:

npm install tacotranslate

Passaggio 2: Crea un account TacoTranslate gratuito

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. È gratis e non richiede l'inserimento di una carta di credito.

All'interno dell'interfaccia di 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 divulgare mai la chiave API segreta read/write negli ambienti di produzione lato client.

Aggiungeremo inoltre due variabili d'ambiente: TACOTRANSLATE_DEFAULT_LOCALE e TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Il codice della locale di fallback predefinita. In questo esempio lo imposteremo su en per l'inglese.
• TACOTRANSLATE_ORIGIN: La "cartella" in cui saranno memorizzate le tue stringhe, come l'URL del tuo sito web. Leggi di più sulle origini qui.

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

Passo 3: Configurazione di TacoTranslate

Per integrare TacoTranslate nella tua applicazione, dovrai creare un client utilizzando le chiavi API indicate 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ù facile riutilizzarlo in seguito. Ora, utilizzando un /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 disponi già di pageProps e di _app.tsx personalizzati, estendi la definizione con le proprietà e il codice riportati sopra.

Passo 4: Implementazione del rendering lato server

TacoTranslate consente il rendering lato server delle tue traduzioni. Questo migliora notevolmente l'esperienza utente mostrando il contenuto tradotto immediatamente, anziché mostrare prima brevemente contenuti non tradotti. Inoltre, possiamo evitare richieste di rete sul client, perché le traduzioni di cui abbiamo bisogno sono già disponibili.

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 solo configurato l'applicazione Next.js con un elenco di lingue supportate. Il passo successivo sarà recuperare le traduzioni per tutte le tue pagine. Per farlo, utilizzerai getTacoTranslateStaticProps o getTacoTranslateServerSideProps in base alle tue esigenze.

Queste funzioni prendono 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 restino 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 essere in grado di usare il componente Translate per tradurre le stringhe all'interno di tutti i tuoi componenti React.

import {Translate} from 'tacotranslate/react';

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

Passo 5: Distribuisci e testa!

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

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!