Com implementar la internacionalització en una aplicació Next.js que utilitza el Pages Router

A mesura que el món es globalitza, és cada vegada 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, divises i formats de data.

En aquest tutorial, explorarem com afegir internacionalització a la teva aplicació React Next.js, amb renderització del costat del servidor. TL;DR: Consulta l'exemple complet aquí.

Aquesta guia és per a aplicacions Next.js que utilitzen el Pages Router.
Si esteu fent servir el App Router, consulteu aquesta guia en el seu lloc.

Pas 1: Instal·lar una biblioteca i18n

Per implementar la internacionalització a la teva aplicació Next.js, primer escollirem una biblioteca d'i18n. Hi ha diverses biblioteques populars, incloent next-intl. Tanmateix, en aquest exemple, farem servir TacoTranslate.

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

Instal·lem-la amb npm al teu terminal:

npm install tacotranslate

Pas 2: Crea un compte gratuït de TacoTranslate

Ara que ja 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 navega a la 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 pots 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 als 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ó de reserva (fallback) predeterminat. En aquest exemple, l'establirem a en per a l'anglès.
• TACOTRANSLATE_ORIGIN: La “carpeta” on s'emmagatzemaran les vostres cadenes, per exemple l'URL del vostre lloc web. Llegiu-ne més sobre els origins aquí.

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

Pas 3: Configuració de TacoTranslate

Per integrar TacoTranslate amb la vostra aplicació, haureu de crear un client utilitzant les claus d'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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Definirem automàticament TACOTRANSLATE_API_KEY d'aquí a poc.

Crear el client en un fitxer separat facilita reutilitzar-lo més endavant. Ara, fent servir un /pages/_app.tsx personalitzat, afegirem el proveïdor 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>
	);
}

Si ja tens pageProps i _app.tsx personalitzats, si us plau, amplia la definició amb les propietats i el codi anteriors.

Pas 4: Implementació del renderitzat al costat del servidor

TacoTranslate permet el renderitzat al costat del servidor de les teves traduccions. Això millora molt 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 peticions de xarxa al client, perquè ja disposem de totes les traduccions que necessitem.

Començarem creant o modificant /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 la comprovació isProduction per adaptar-la a la teva configuració. Si true, TacoTranslate mostrarà la clau API pública. Si estem en un entorn local, de proves o de staging (isProduction is false), farem servir la clau API secreta read/write per assegurar-nos que les noves cadenes s'enviïn per a traducció.

Fins ara, només hem configurat l'aplicació Next.js amb una llista d'idiomes compatibles. El següent que farem és obtenir les traduccions per a totes les teves pàgines. Per fer-ho, faràs servir o bé getTacoTranslateStaticProps o bé getTacoTranslateServerSideProps segons les teves necessitats.

Aquestes funcions reben tres arguments: un objecte Next.js Static Props Context, la configuració per a TacoTranslate i propietats opcionals de Next.js. Tingues en compte que revalidate a getTacoTranslateStaticProps està establert a 60 per defecte, de manera que les teves traduccions es mantinguin al dia.

Per utilitzar qualsevol de les dues funcions en una pàgina, suposem que tens un fitxer de pàgina com /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!"/>;
}

Ara hauríeu de poder utilitzar el component Translate per traduir cadenes en tots els vostres components de React.

import {Translate} from 'tacotranslate/react';

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

Pas 5: Desplega i prova!

Hem acabat! La teva aplicació React ara es traduirà automàticament quan afegeixis qualsevol cadena a un component Translate. Cal tenir en compte que només els entorns amb permisos read/write sobre la clau de l'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 d'API d'aquest tipus, afegint noves cadenes abans de publicar-la. Això evitarà que ningú ningú robi la vostra clau secreta de l'API i, potencialment, saturi el vostre projecte de traducció afegint 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 App Router! Si et trobes amb algun problema, no dubtis a posar-te en contacte, i estarem encantats d'ajudar-te.

TacoTranslate et permet localitzar automàticament les teves aplicacions React cap a i des de més de 75 llengües. Comença avui mateix!