La millor solució per a la internacionalització (i18n) en aplicacions Next.js

Com funciona

A mesura que el món es globalitza, és cada vegada més important que els desenvolupadors web construeixin 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 tutorial, explorarem com afegir la internacionalització a la teva aplicació React Next.js, amb renderitzat al costat del servidor. TL;DR: Vegeu l'exemple complet aquí.

Aquesta guia és per a aplicacions Next.js que utilitzen el Pages Router.
Si utilitzeu el App 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, incloent-hi next-intl. Tanmateix, en aquest exemple utilitzarem TacoTranslate.

TacoTranslate tradueix automàticament les teves cadenes a qualsevol idioma mitjançant IA d'avantguarda, i et allibera de la tediosa gestió dels fitxers JSON.

Instal·lem-lo 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 API associades. Crea un compte aquí. És gratuït i no requereix que afegeixis una targeta de crèdit.

A la interfície d'usuari de l'aplicació TacoTranslate, crea un projecte i ves a la pestanya de claus de l'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

Assegura't de no filtrar mai la clau 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, el configurarem a en per a l'anglès.
• TACOTRANSLATE_ORIGIN: La "carpeta" on s'emmagatzemaran les teves cadenes, com per exemple la URL del teu lloc web. Més informació sobre els orígens aquí.

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

Pas 3: Configuració de TacoTranslate

Per integrar TacoTranslate amb la teva aplicació, hauràs de crear un client utilitzant les claus de l'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;

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 personalitzats pageProps i _app.tsx, si us plau amplia la definició amb les propietats i el codi indicats més amunt.

Pas 4: Implementació del renderitzat al servidor

TacoTranslate permet la renderització al servidor de les teves traduccions. Això millora considerablement l'experiència d'usuari, ja que mostra el contingut traduït immediatament, en lloc d'un primer flaix de contingut sense traduir. A més, podem evitar fer peticions 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 farà visible la clau d'API pública. Si estem en un entorn local, de proves o de staging (isProduction is false), farem servir la clau d'API secreta read/write per assegurar que les noves cadenes s'enviïn per a la traducció.

Fins ara, només hem configurat l'aplicació Next.js amb una llista d'idiomes compatibles. El següent que farem serà obtenir les traduccions de totes les vostres pàgines. Per fer-ho, utilitzareu o bé getTacoTranslateStaticProps o bé getTacoTranslateServerSideProps segons els vostres requisits.

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

Per utilitzar qualsevol d’aquestes funcions 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 ja hauries de poder utilitzar el Translate component per traduir cadenes en tots els teus components React.

import {Translate} from 'tacotranslate/react';

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

Pas 5: Desplega i prova!

Ja hem acabat! La vostra aplicació Next.js 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 d'API podran crear noves cadenes per traduir. Us recomanem disposar d'un entorn de preproducció tancat i segur on pugueu provar la vostra 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 vostra clau d'API secreta i que, potencialment, el vostre projecte de traducció s'infli afegint noves cadenes 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 App 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!