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

A mesura que el món es globalitza, é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 us permet adaptar l'aplicació a diferents idiomes, monedes i formats de data.

En aquest tutorial, veurem com afegir internacionalització a la vostra aplicació React Next.js, amb renderitzat del costat del servidor. TL;DR: Vegeu l'exemple complet aquí.

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

Pas 1: Instal·la una biblioteca i18n

Per implementar la internacionalització a la teva aplicació Next.js, primer triarem una biblioteca d'i18n. Hi ha diverses biblioteques populars, incloses next-intl. Tot i això, en aquest exemple, farem servir TacoTranslate.

TacoTranslate tradueix automàticament les teves cadenes a qualsevol idioma utilitzant IA d'avantguarda, 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 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 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 pestanya de claus API. Crea una clau read i una altra 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, pots afegir-les a un fitxer .env a l'arrel del teu projecte.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assegura't 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ó per defecte (fallback). En aquest exemple, l'establirem a en per a l'anglès.
• TACOTRANSLATE_ORIGIN: La “carpeta” on s'emmagatzemaran les teves cadenes, com l'URL del teu lloc web. Llegeix-ne més sobre els orígens aquí.

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

Pas 3: Configurar TacoTranslate

Per integrar TacoTranslate amb la teva aplicació, hauràs de crear un client utilitzant les claus API esmentades anteriorment. Per exemple, crea 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;

En breu definirem automàticament TACOTRANSLATE_API_KEY.

Crear el client en un fitxer separat facilita tornar-lo a utilitzar més endavant. Ara, utilitzant un /pages/_app.tsx personalitzat, hi 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 disposes de pageProps i _app.tsx personalitzats, si us plau, amplia la definició amb les propietats i el codi indicats més amunt.

Pas 4: Implementació del renderitzat del costat del servidor

TacoTranslate permet el renderitzat al costat del servidor de les vostres traduccions. Això millora molt l'experiència d'usuari mostrant el contingut traduït immediatament, en lloc d'un parpelleig inicial de contingut sense traduir. A més, podem evitar sol·licituds de xarxa des del 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 exposarà la clau d'API pública. Si estem en un entorn local, de proves o de staging (isProduction is false), utilitzarem la clau d'API secreta read/write per assegurar que les noves cadenes s'enviïn per a ser traduïdes.

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 de totes les teves pàgines. Per fer-ho, hauràs d'utilitzar o bé getTacoTranslateStaticProps o bé getTacoTranslateServerSideProps segons els teus requisits.

Aquestes funcions prenen tres arguments: un objecte Next.js Static Props Context, la configuració per a TacoTranslate i propietats opcionals de Next.js. Observa que revalidate a getTacoTranslateStaticProps està establert a 60 per defecte, perquè les teves traduccions es mantinguin actualitzades.

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 hauries de poder utilitzar el component Translate per traduir cadenes dins de tots els teus components React.

import {Translate} from 'tacotranslate/react';

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

Pas 5: Desplega i prova!

Ja està! 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 de l'API podran crear noves cadenes per traduir. Recomanem disposar d’un entorn de preproducció tancat i segur on puguis provar la teva aplicació de producció amb una clau d'API d’aquest tipus, afegint noves cadenes abans de posar-la en producció. Això evitarà que algú robi la teva clau d'API secreta i, potencialment, que s'infli el teu projecte de traducció amb noves cadenes no relacionades.

Assegureu-vos de consultar l'exemple complet al nostre perfil de GitHub. Allà també hi trobareu un exemple de com fer-ho utilitzant el App Router! Si teniu algun problema, no dubteu a posar-vos en contacte, i estarem més que encantats d'ajudar-vos.

TacoTranslate us permet localitzar automàticament les vostres aplicacions React, ràpidament, cap a i des de més de 75 idiomes. Comenceu avui mateix!