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

Com funciona

A mesura que el món es globalitza, és cada cop més important per als desenvolupadors web crear aplicacions que puguin atendre usuaris de diferents països i cultures. Una de les maneres clau d’aconseguir-ho és a través de la internacionalització (i18n), que et permet adaptar la teva aplicació a diferents idiomes, monedes 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: Vegeu l’exemple complet aquí.

Aquesta guia és per a aplicacions Next.js que utilitzen el Pages Router.
Si utilitzeu el App Router, si us plau, consulteu aquesta guia.

Pas 1: Instal·la una biblioteca i18n

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

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

Instal·lem-ho usant npm a la vostra 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 les tecles API. Crea una tecla read i una tecla read/write. Les desarem com a variables d'entorn. La tecla read és la que anomenem public, i la tecla 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 en 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 configuració regional predeterminat per defecte. En aquest exemple, el configurarem com a en per a anglès.
• TACOTRANSLATE_ORIGIN: La "carpeta" on es desaran les teves cadenes, com per exemple la URL del teu lloc web. Llegiu més 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 vostra aplicació, haureu de crear un client amb les claus API anteriors. 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 fa que sigui més fàcil d’utilitzar de nou 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 esmentats anteriorment.

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 de l’usuari mostrant contingut traduït immediatament, en lloc d’un flaix de contingut no traduït primer. A més, podem evitar les 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 pública de l’API. Si estem en un entorn local, de proves o staging (isProduction is false), utilitzarem la clau secreta read/write de l’API per assegurar-nos 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 per a totes les teves pàgines. Per fer-ho, utilitzaràs ja sigui getTacoTranslateStaticProps o getTacoTranslateServerSideProps, segons les teves necessitats.

Aquestes funcions prenen tres arguments: un objecte Next.js Static Props Context, la configuració per a TacoTranslate, i propietats opcionals de Next.js. Tingueu en compte que revalidate a getTacoTranslateStaticProps està configurat a 60 per defecte, perquè 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 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: Deploy i prova!

Hem acabat! La teva aplicació Next.js 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 de proves 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 funcionament. Això evitarà que algú apropi la teva clau API secreta i, potencialment, que s’inflin el 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 utilitzant el App Router ! Si tens algun problema, no dubtis a contactar, i estarem més que encantats 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!