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

Con la crescente globalizzazione, è sempre più importante che gli sviluppatori web realizzino applicazioni in grado di soddisfare utenti provenienti da diversi paesi e culture. Uno dei modi chiave per raggiungere questo obiettivo è l'internazionalizzazione (i18n), che consente di adattare la tua applicazione a lingue, valute e formati di data differenti.

In questo articolo, 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 App Router.
Se utilizzi il Pages Router, consulta invece questa guida.

Passo 1: Installa una libreria i18n

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

TacoTranslate traduce automaticamente le tue stringhe in qualsiasi lingua utilizzando l'IA 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 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'aggiunta 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 radice 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 lingua di fallback predefinita. In questo esempio lo imposteremo 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, clicca qui.

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

Passaggio 3: Configurare TacoTranslate

Per integrare TacoTranslate con la tua applicazione, dovrai creare un client utilizzando le chiavi API precedenti. 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Definiremo automaticamente TACOTRANSLATE_API_KEY e TACOTRANSLATE_PROJECT_LOCALE a breve.

Creare il client in un file separato lo rende facile da riutilizzare in seguito. getLocales è semplicemente una funzione di utilità con una gestione degli errori integrata. Ora, crea un file chiamato /app/[locale]/tacotranslate.tsx, dove implementeremo il provider TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Nota il 'use client'; che indica che si tratta di un componente client.

Con il provider di contesto ora pronto, crea un file chiamato /app/[locale]/layout.tsx, il layout principale della nostra applicazione. Nota che questo percorso contiene una cartella che utilizza Dynamic Routes, dove [locale] è il parametro dinamico.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

La prima cosa da notare qui è che stiamo usando il nostro parametro Dynamic Route [locale] per recuperare le traduzioni per quella lingua. Inoltre, generateStaticParams si assicura che tutti i codici di locale che hai attivato per il tuo progetto siano pre-renderizzati.

Ora costruiamo la nostra prima pagina! Crea un file chiamato /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

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

Nota la variabile revalidate che dice a Next.js di ricostruire la pagina dopo 60 secondi e di mantenere le tue traduzioni aggiornate.

Passo 4: Implementazione del rendering lato server

TacoTranslate supporta il rendering lato server. Ciò migliora notevolmente l'esperienza utente mostrando i contenuti tradotti immediatamente, anziché un lampo iniziale di contenuti non tradotti. Inoltre, possiamo evitare richieste di rete dal client, perché abbiamo già le traduzioni necessarie per la pagina che l'utente sta visualizzando.

Per configurare il rendering lato server, crea o modifica /next.config.js:

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

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Modifica il controllo isProduction per adattarlo alla tua configurazione. Se true, TacoTranslate esporrà 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.

Per garantire che il routing e il reindirizzamento funzionino come previsto, dovremo creare un file chiamato /middleware.ts. Usando Middleware, possiamo reindirizzare gli utenti alle pagine presentate nella loro lingua preferita.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Assicurati di configurare il matcher in conformità con la documentazione sui Middleware di Next.js.

Lato client, puoi modificare il cookie locale per cambiare quale sia la lingua preferita dell'utente. Consulta il codice di esempio completo per idee su come farlo!

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 saranno in grado di creare nuove stringhe da tradurre. Raccomandiamo di disporre di un ambiente di staging chiuso e sicuro dove poter testare la tua applicazione di produzione con una chiave API di questo tipo, aggiungendo nuove stringhe prima della pubblicazione. 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 Pages 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!