Com implementar la internacionalització en una aplicació Next.js que fa servir el 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 internacionalització a la teva aplicació React Next.js, amb renderització del costat del servidor. TL;DR: Vegeu l'exemple complet aquí.

Aquesta guia és per a aplicacions Next.js que utilitzen el App Router.
Si utilitzeu el Pages Router, vegeu aquesta guia en comptes d'això.

Pas 1: Instal·la una biblioteca i18n

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

TacoTranslate tradueix automàticament les teves cadenes a qualsevol idioma utilitzant IA d’última generació, i et lliura de la gestió tediosa dels fitxers JSON.

Instal·lem-lo fent servir npm a la teva terminal:

npm install tacotranslate

Pas 2: Crea un compte gratuït a 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 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 navega fins a la pestanya de claus API. Crea una clau read i una altra 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, podries afegir-les a un fitxer .env a la carpeta arrel del teu projecte.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assegura't de no divulgar mai la clau secreta read/write de l'API als entorns de producció del costat client.

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

• TACOTRANSLATE_DEFAULT_LOCALE: El codi de localització predeterminada de reserva. En aquest exemple, l’establirem a en per a l’anglès.
• TACOTRANSLATE_ORIGIN: La “carpeta” on es desaran les teves cadenes, com per exemple la URL del teu lloc web. Llegeix més sobre els orígens aquí.

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

Pas 3: Configurant TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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;

Definirem automàticament TACOTRANSLATE_API_KEY i TACOTRANSLATE_PROJECT_LOCALE en breu.

La creació del client en un fitxer separat facilita el seu ús més endavant. getLocales és només una funció d'utilitat amb una mica de gestió d'errors integrada. Ara, creeu 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>
	);
}

Tingues en compte el 'use client'; que indica que aquest és un component client.

Amb el proveïdor de context ja llest per funcionar, crea un fitxer anomenat /app/[locale]/layout.tsx, el disseny arrel a la nostra aplicació. Tingues en compte que aquest camí 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>
	);
}

El primer que cal destacar aquí és que estem utilitzant el nostre paràmetre de Dynamic Route [locale] per obtenir les traduccions d'aquella llengua. A més a més, generateStaticParams està assegurant que tots els codis de localització que tens activats pel 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 reconstruïsca la pàgina després de 60 segons i mantingui les vostres traduccions actualitzades.

Pas 4: Implementació del renderitzat del costat del servidor

TacoTranslate admet renderització al servidor. Això millora enormement l'experiència de l'usuari mostrant contingut traduït immediatament, en comptes d'un flaix de contingut no traduït primer. A més, podem evitar les sol·licituds de xarxa al client, perquè ja disposem de les traduccions que necessitem per a la pàgina que l'usuari està visualitzant.

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 mostrarà la clau pública de l’API. Si estem en un entorn local, de prova o staging (isProduction is false), utilitzarem la clau secreta read/write de l’API per assegurar-nos que es matin noves cadenes per traducció.

Per assegurar que l'enrutament i la redirecció funcionin com s'espera, caldrà 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ó de Next.js Middleware.

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

Pas 5: Desplega i prova!

Hem acabat! La teva aplicació React ara es traduirà automàticament quan afegeixis qualsevol cadena a un component Translate. Tingues en compte que només els entorns amb permisos read/write a la clau API podran crear noves cadenes per traduir. Recomanem tenir un entorn d'etapa tancat i segur on puguis provar la teva aplicació de producció amb una clau API d'aquest tipus, afegint noves cadenes abans d'anar en viu. Això evitarà que algú robi la teva clau API secreta i que el projecte de traducció s'engreixi innecessàriament amb noves cadenes no relacionades.

Assegura't de consultar l'exemple complet al nostre perfil de GitHub. Allà, també trobaràs un exemple de com fer-ho utilitzant el Pages Router! Si tens cap problema, no dubtis a contactar-nos, i estarem més que contents d'ajudar-te.

TacoTranslate et permet localitzar automàticament les teves aplicacions React ràpidament cap a i des de qualsevol idioma. Comença avui mateix!