Com implementar la internacionalització en una aplicació Next.js que utilitza l'App Router

A mesura que el món es torna més globalitzat, és cada cop més important que els desenvolupadors web creïn aplicacions que puguin atendre usuaris de diferents països i cultures. Una de les maneres clau d'aconseguir-ho és mitjançant la internacionalització (i18n), que et permet adaptar la teva aplicació a diferents idiomes, monedes i formats de data.

En aquest article, explorarem com afegir la internacionalització a la teva aplicació React Next.js, amb renderitzat al servidor. TL;DR: Vegeu l'exemple complet aquí.

Aquesta guia és per a aplicacions Next.js que utilitzen l' App Router.
Si utilitzeu el Pages Router, consulteu aquesta altra guia.

Pas 1: Instal·la una biblioteca d'i18n

Per implementar la internacionalització a la teva aplicació Next.js, primer triarem una biblioteca d’i18n. Hi ha diverses biblioteques populars, inclosa next-intl. En aquest exemple, però, farem servir TacoTranslate.

TacoTranslate tradueix automàticament les teves cadenes a qualsevol idioma fent servir IA d'última generació i t'allibera de la tediosa gestió d'arxius JSON.

Instal·lem-ho amb npm al teu terminal:

npm install tacotranslate

Pas 2: Crea un compte gratuït de TacoTranslate

Ara que tens el mòdul instal·lat, és hora de crear el teu compte de TacoTranslate, un projecte de traducció i les claus d'API associades. Crea un compte aquí. És gratuït i no requereix que afegeixis una targeta de crèdit.

Dins de la interfície d'usuari de l'aplicació TacoTranslate, crea un projecte i ves a la seva pestanya de claus API. Crea una clau read i una clau read/write. Les guardarem com a variables d'entorn. La clau read és la que anomenem public i la clau read/write és secret. Per exemple, les podries afegir a un fitxer .env a l'arrel del teu projecte.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assegureu-vos de no filtrar mai la clau d'API secreta read/write en entorns de producció del costat del client.

També afegirem dues variables d'entorn més: TACOTRANSLATE_DEFAULT_LOCALE i TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: El codi de localització predeterminat que s'utilitza com a fallback. En aquest exemple, el fixarem a en per a l'anglès.
• TACOTRANSLATE_ORIGIN: La “carpeta” on s'emmagatzemaran les teves cadenes, com ara la URL del teu lloc web. Llegiu més sobre els origins aquí.

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

Pas 3: Configurar TacoTranslate

Per integrar TacoTranslate amb la vostra aplicació, haureu de crear un client utilitzant les claus API esmentades anteriorment. Per exemple, creeu un fitxer anomenat /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;

En breu definirem automàticament TACOTRANSLATE_API_KEY i TACOTRANSLATE_PROJECT_LOCALE.

Crear el client en un fitxer separat facilita tornar-lo a utilitzar més endavant. getLocales és només una funció d'utilitat amb gestió d'errors integrada. Ara, crea un fitxer anomenat /app/[locale]/tacotranslate.tsx, on implementarem el proveïdor 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>
	);
}

Fixeu-vos en 'use client'; que indica que aquest és un component client.

Ara que el proveïdor de context està a punt, crea un fitxer anomenat /app/[locale]/layout.tsx, el layout arrel de la nostra aplicació. Tingues en compte que aquesta ruta té una carpeta que utilitza Dynamic Routes, on [locale] és el paràmetre dinàmic.

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 primera cosa a tenir en compte aquí és que estem fent servir el nostre paràmetre Dynamic Route [locale] per obtenir les traduccions d'aquest idioma. A més, generateStaticParams s'assegura que tots els codis de localització que has activat al teu projecte estiguin pre-renderitzats.

Ara, construïm la nostra primera pàgina! Crea un fitxer anomenat /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!" />
	);
}

Tingueu en compte la variable revalidate que indica a Next.js que torni a generar la pàgina després de 60 segons i mantingui les vostres traduccions actualitzades.

Pas 4: Implementació del renderitzat al costat del servidor

TacoTranslate admet el renderitzat al costat del servidor. Això millora notablement l'experiència d'usuari en mostrar el contingut traduït immediatament, en lloc d'un breu parpelleig de contingut sense traduir. A més, podem evitar les peticions de xarxa des del client, perquè ja disposem de les traduccions que necessitem per a la pàgina que l'usuari està veient.

Per configurar el renderitzat del costat del servidor, 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 la comprovació isProduction per adaptar-la a la teva configuració. Si true, TacoTranslate exposarà la clau API pública. Si estem en un entorn local, de proves o de preproducció (isProduction is false), farem servir la clau API secreta read/write per assegurar que les noves cadenes s'enviïn per a la traducció.

Per assegurar que l'enrutament i les redireccions funcionin com s'espera, haurem de crear un fitxer anomenat /middleware.ts. Utilitzant Middleware, podem redirigir els usuaris a pàgines presentades en el seu idioma preferit.

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);
}

Assegureu-vos de configurar el matcher d'acord amb la documentació del middleware de Next.js.

Al client, pots modificar la cookie locale per canviar quin és l'idioma preferit de l'usuari. Consulta el codi d'exemple complet per idees sobre com fer-ho!

Pas 5: Desplega i prova!

Ja està! La vostra aplicació React ara es traduirà automàticament quan afegiu qualsevol cadena a un component Translate. Tingueu en compte que només els entorns amb permisos read/write sobre la clau API podran crear noves cadenes per traduir. Us recomanem tenir un entorn de proves tancat i segur on pugueu provar la vostra aplicació de producció amb una clau API d’aquest tipus, afegint-hi noves cadenes abans d’anar a producció. Això evitarà que qualsevol persona qualsevol persona robi la vostra clau API secreta i, potencialment, que el vostre projecte de traducció s'ompli amb cadenes noves i no relacionades.

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!