Cómo implementar la internacionalización en una aplicación Next.js que usa el Pages Router

A medida que el mundo se globaliza, es cada vez más importante que los desarrolladores web creen aplicaciones que puedan atender a usuarios de distintos países y culturas. Una de las formas clave de lograr esto es mediante la internacionalización (i18n), que te permite adaptar tu aplicación a diferentes idiomas, monedas y formatos de fecha.

En este tutorial, exploraremos cómo añadir internacionalización a tu aplicación React Next.js, con renderizado del lado del servidor. TL;DR: Consulta el ejemplo completo aquí.

Esta guía es para aplicaciones Next.js que usan el Pages Router.
Si está usando el App Router, consulte esta guía en su lugar.

Paso 1: Instalar una librería de i18n

Para implementar la internacionalización en su aplicación Next.js, primero elegiremos una biblioteca de i18n. Existen varias bibliotecas populares, incluyendo next-intl. Sin embargo, en este ejemplo usaremos TacoTranslate.

TacoTranslate traduce automáticamente sus cadenas a cualquier idioma usando IA de vanguardia y le libera de la tediosa gestión de archivos JSON.

Instalémoslo usando npm en su terminal:

npm install tacotranslate

Paso 2: Crea una cuenta gratuita de TacoTranslate

Ahora que tienes el módulo instalado, es momento de crear tu cuenta de TacoTranslate, un proyecto de traducción y las claves API asociadas. Crea una cuenta aquí. Es gratis, y no requiere que añadas una tarjeta de crédito.

Dentro de la interfaz de la aplicación TacoTranslate, crea un proyecto y navega a la pestaña de claves API. Crea una clave read, y una read/write. Las guardaremos como variables de entorno. La clave read es lo que llamamos public, y la clave read/write es secret. Por ejemplo, podrías agregarlas a un archivo .env en la raíz de tu proyecto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Asegúrate de no filtrar nunca la clave API secreta read/write a los entornos de producción del lado del cliente.

También añadiremos dos variables de entorno más: TACOTRANSLATE_DEFAULT_LOCALE y TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: El código de locale de respaldo predeterminado. En este ejemplo, lo estableceremos en en para inglés.
• TACOTRANSLATE_ORIGIN: La “carpeta” donde se almacenarán tus cadenas, como la URL de tu sitio web. Lee más sobre los orígenes aquí.

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

Paso 3: Configurar TacoTranslate

Para integrar TacoTranslate con tu aplicación, necesitarás crear un cliente usando las claves API indicadas anteriormente. Por ejemplo, crea un archivo llamado /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;

Pronto definiremos automáticamente TACOTRANSLATE_API_KEY.

Crear el cliente en un archivo separado facilita volver a usarlo más tarde. Ahora, usando un /pages/_app.tsx personalizado, añadiremos el proveedor 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 ya tienes definiciones personalizadas de pageProps y _app.tsx, por favor extiende la definición con las propiedades y el código anteriores.

Paso 4: Implementación del renderizado del lado del servidor

TacoTranslate permite el renderizado del lado del servidor de tus traducciones. Esto mejora enormemente la experiencia del usuario al mostrar el contenido traducido de forma inmediata, en lugar de un breve parpadeo de contenido sin traducir al principio. Además, podemos omitir las solicitudes de red desde el cliente, porque ya tenemos todas las traducciones que necesitamos.

Comenzaremos por crear o modificar /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 comprobación isProduction para adaptarla a tu configuración. Si true, TacoTranslate mostrará la clave pública de la API. Si estamos en un entorno local, de pruebas o de staging (isProduction is false), utilizaremos la clave secreta read/write de la API para asegurarnos de que las nuevas cadenas se envíen para su traducción.

Hasta ahora, solo hemos configurado la aplicación Next.js con una lista de idiomas compatibles. Lo siguiente que haremos es obtener las traducciones de todas tus páginas. Para hacerlo, usarás getTacoTranslateStaticProps o getTacoTranslateServerSideProps según tus necesidades.

Estas funciones toman tres argumentos: un objeto Next.js Static Props Context, la configuración para TacoTranslate y propiedades opcionales de Next.js. Ten en cuenta que revalidate en getTacoTranslateStaticProps está establecido en 60 por defecto, para que tus traducciones se mantengan actualizadas.

Para usar cualquiera de las dos funciones en una página, asumamos que tienes un archivo de página como /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!"/>;
}

Ahora deberías poder usar el componente Translate para traducir cadenas dentro de todos tus componentes de React.

import {Translate} from 'tacotranslate/react';

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

Paso 5: ¡Desplegar y probar!

¡Listo! Tu aplicación React ahora se traducirá automáticamente cuando añadas cualquier cadena a un componente Translate. Ten en cuenta que solo los entornos con permisos read/write en la clave de la API podrán crear nuevas cadenas para traducir. Recomendamos disponer de un entorno de staging cerrado y seguro donde puedas probar tu aplicación de producción con una clave de API como esa, añadiendo nuevas cadenas antes de ponerla en producción. Esto evitará que alguien robe tu clave secreta de la API y, potencialmente, que se sature tu proyecto de traducción al añadirse cadenas nuevas no relacionadas.

Asegúrate de consultar el ejemplo completo en nuestro perfil de GitHub. ¡Allí también encontrarás un ejemplo de cómo hacerlo usando el App Router]! Si encuentras algún problema, no dudes en ponerte en contacto, y estaremos encantados de ayudarte.

TacoTranslate te permite localizar automáticamente tus aplicaciones React de forma rápida y sencilla a más de 75 idiomas y desde ellos. ¡Comienza hoy!