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 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 renderitzat 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 utilitzeu el App Router, consulteu aquesta guia en canvi.

Pas 1: Instal·la una biblioteca i18n

Per implementar la internacionalització a la teva aplicació Next.js, primer triem una biblioteca i18n. Hi ha diverses biblioteques populars, incloent-hi next-intl. Tanmateix, en aquest exemple, utilitzarem TacoTranslate.

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

Instal·lem-ho usant 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 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 podries afegir a un fitxer .env a la carpeta arrel del teu projecte.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assegureu-vos de no filtrar 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ó predeterminat per a usar com a recurs. En aquest exemple, el configurarem a en per a anglès.
• TACOTRANSLATE_ORIGIN: La "carpeta" on s’emmagatzemaran les teves cadenes, com per exemple l’URL del teu lloc web. Llegeix més sobre els orígens aquí.

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

Pàs 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Definirem automàticament TACOTRANSLATE_API_KEY en breu.

Crear el client en un fitxer separat facilita tornar-lo a utilitzar més endavant. Ara, utilitzant 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 indicats anteriorment.

Pas 4: Implementació del renderitzat del costat del servidor

TacoTranslate permet el renderitzat al costat del servidor de les teves traduccions. Això millora enormement l'experiència de l'usuari mostrant el contingut traduït immediatament, en lloc d'un flaix de contingut no traduït primer. A més, podem evitar les sol·licituds de xarxa al client, perquè ja tenim 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'),
	});
};

Modifiqueu la comprovació isProduction per adaptar-la a la vostra configuració. Si true, TacoTranslate mostrarà la clau d'API pública. Si estem en un entorn local, de prova o de preparació (isProduction is false), utilitzarem la clau d'API secret read/write per assegurar-nos que s'enviïn noves cadenes per a la seva traducció.

Fins ara, només hem configurat l'aplicació Next.js amb una llista d'idiomes compatibles. El següent que farem és buscar traduccions per a totes les vostres pàgines. Per fer-ho, utilitzareu getTacoTranslateStaticProps o getTacoTranslateServerSideProps en funció dels vostres requisits.

Aquestes funcions prenen tres arguments: un objecte Next.js Static Props Context , configuració per a TacoTranslate i propietats Next.js opcionals. Tingueu en compte que revalidate en getTacoTranslateStaticProps està establert en 60 per defecte, de manera que les traduccions estiguin actualitzades.

Per utilitzar qualsevol funció en una pàgina, suposem que teniu 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!

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 en la clau API podran crear noves cadenes per traduir. Recomanem disposar d’un entorn de staging tancat i segur on puguis provar la teva aplicació de producció amb una clau API d’aquest tipus, afegint noves cadenes abans de posar-la en marxa. Això evitarà que qualsevol pugui robar la teva clau API secreta i, potencialment, inflar el teu projecte de traducció afegint cadenes noves i no relacionades.

Assegura't de consultar l'exemple complet al nostre perfil de GitHub. Allà, també trobaràs un exemple de com fer-ho amb el App Router!\ Si tens algun problema, no dubtis en posar-te en contacte, i estarem encantats d'ajudar-te.

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