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

Man mano che il mondo diventa più globalizzato, è sempre più importante per gli sviluppatori web creare applicazioni in grado di soddisfare utenti provenienti da diversi paesi e culture. Uno dei modi chiave per raggiungere questo obiettivo è attraverso l'internazionalizzazione (i18n), che consente di adattare la tua applicazione a diverse lingue, valute e formati di data.

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

Questa guida è per applicazioni Next.js che utilizzano il App Router.
Se stai usando 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. Ci sono diverse librerie popolari, inclusa next-intl. In questo esempio, tuttavia, useremo TacoTranslate.

TacoTranslate traduce automaticamente le tue stringhe in qualsiasi lingua utilizzando un'intelligenza artificiale all'avanguardia, liberandoti dalla noiosa 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’aggiunta di una carta di credito.

All’interno dell’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 al 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 agli ambienti di produzione lato client.

Aggiungeremo anche altre 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” dove verranno 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 con la tua applicazione, dovrai creare un client utilizzando le chiavi API precedentemente ottenute. 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 rende facile riutilizzarlo in seguito. getLocales è semplicemente una funzione di utilità con alcune gestione errori integrate. 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 'use client'; che indica che questo è un componente client.

Con il context provider ora pronto, crea un file chiamato /app/[locale]/layout.tsx, il layout principale nella 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 di Dynamic Route [locale] per recuperare le traduzioni per quella lingua. Inoltre, generateStaticParams assicura che tutti i codici di localizzazione che hai attivato per il tuo progetto siano prerenderizzati.

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 indica a Next.js di ricostruire la pagina dopo 60 secondi, per mantenere le tue traduzioni aggiornate.

Passo 4: Implementazione del rendering lato server

TacoTranslate supporta il rendering lato server. Questo migliora notevolmente l'esperienza utente mostrando immediatamente il contenuto tradotto, invece di un breve flash di contenuto non tradotto all'inizio. Inoltre, possiamo evitare richieste di rete sul client, perché abbiamo già le traduzioni di cui abbiamo bisogno 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 in base alla tua configurazione. Se true, TacoTranslate utilizzerà la chiave API pubblica. Se siamo 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. Utilizzando 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 di Next.js Middleware.

Sul client, puoi modificare il cookie locale per cambiare la lingua preferita dall’utente. Consulta il codice completo dell’esempio per idee su come farlo!

Passo 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. Raccomandiamo di avere 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 di andare live. 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.

Assicurati di dare un’occhiata all’esempio completo presente nel nostro profilo GitHub. Lì troverai anche un esempio di come farlo utilizzando il Pages Router ! Se incontri dei problemi, non esitare a contattarci, saremo più che felici di aiutarti.

TacoTranslate ti permette di localizzare automaticamente le tue applicazioni React rapidamente da e verso qualsiasi lingua. Inizia oggi stesso!