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

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

En este artículo, exploraremos cómo agregar internacionalización a tu aplicación React Next.js, con renderizado del lado del servidor. TL;DR: Ve el ejemplo completo aquí.

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

Paso 1: Instala una biblioteca i18n

Para implementar la internacionalización en tu aplicación Next.js, primero elegiremos una librería i18n. Hay varias librerías populares, incluyendo next-intl. Sin embargo, en este ejemplo, usaremos TacoTranslate.

TacoTranslate traduce automáticamente tus cadenas a cualquier idioma utilizando inteligencia artificial de vanguardia, y te libera de la tediosa gestión de archivos JSON.

Instalémoslo usando npm en tu terminal:

npm install tacotranslate

Paso 2: Crea una cuenta gratuita en 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 agregues 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 clave 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 nunca filtrar la clave API secreta read/write en los entornos de producción del lado del cliente.

También agregaremos dos variables de entorno más: TACOTRANSLATE_DEFAULT_LOCALE y TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: El código de configuración regional predeterminado de respaldo. 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 orígenes aquí.

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

Paso 3: Configurando TacoTranslate

Para integrar TacoTranslate con tu aplicación, necesitarás crear un cliente utilizando las claves API mencionadas 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Pronto definiremos automáticamente TACOTRANSLATE_API_KEY y TACOTRANSLATE_PROJECT_LOCALE.

Crear el cliente en un archivo separado facilita su reutilización más adelante. getLocales es solo una función utilitaria con algo de manejo de errores incorporado. Ahora, crea un archivo llamado /app/[locale]/tacotranslate.tsx, donde implementaremos el proveedor TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Nota el 'use client'; que indica que este es un componente del cliente.

Con el proveedor de contexto ahora listo, crea un archivo llamado /app/[locale]/layout.tsx, el layout raíz en nuestra aplicación. Nota que esta ruta tiene una carpeta que utiliza Dynamic Routes, donde [locale] es el parámetro dinámico.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Lo primero que hay que señalar aquí es que estamos usando nuestro parámetro de Dynamic Route [locale] para obtener las traducciones de ese idioma. Además, generateStaticParams se asegura de que todos los códigos de localización que tienes activados para tu proyecto se pre-rendericen.

¡Ahora, construyamos nuestra primera página! Crea un archivo llamado /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Nota la variable revalidate que indica a Next.js que reconstruya la página después de 60 segundos y mantenga tus traducciones actualizadas.

Paso 4: Implementando renderizado del lado del servidor

TacoTranslate soporta renderizado del lado del servidor. Esto mejora enormemente la experiencia del usuario al mostrar contenido traducido de inmediato, en lugar de un breve destello de contenido sin traducir primero. Además, podemos omitir solicitudes de red en el cliente, porque ya tenemos las traducciones que necesitamos para la página que el usuario está viendo.

Para configurar el renderizado del lado del servidor, crea o modifica /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Modifique la verificación de isProduction para que se adapte a su configuración. Si true, TacoTranslate mostrará la clave de API pública. Si estamos en un entorno local, de prueba o de ensayo (isProduction is false), usaremos la clave de API de read/write secreta para asegurarnos de que se envíen nuevas cadenas para su traducción.

Para asegurar que el enrutamiento y la redirección funcionen como se espera, necesitaremos crear un archivo llamado /middleware.ts. Usando Middleware, podemos redirigir a los usuarios a páginas presentadas en su idioma preferido.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Asegúrate de configurar el matcher de acuerdo con la documentación de Middleware de Next.js.

En el cliente, puedes modificar la cookie locale para cambiar cuál es el idioma preferido del usuario. ¡Por favor, consulta el código de ejemplo completo para ideas sobre cómo hacerlo!

Paso 5: ¡Despliega y prueba!

¡Hemos terminado! Tu aplicación React ahora se traducirá automáticamente cuando agregues cualquier cadena a un componente Translate. Ten en cuenta que solo los entornos con permisos read/write en la clave API podrán crear nuevas cadenas para ser traducidas. Recomendamos tener un entorno de staging cerrado y seguro donde puedas probar tu aplicación de producción con una clave API de ese tipo, agregando nuevas cadenas antes de lanzarla en vivo. Esto evitará que alguien robe tu clave API secreta y potencialmente haga que tu proyecto de traducción se sobrecargue con cadenas nuevas y no relacionadas.

Asegúrate de revisar el ejemplo completo en nuestro perfil de GitHub. Ahí también encontrarás un ejemplo de cómo hacerlo usando el Pages Router ¡Si tienes algún problema, no dudes en contactarnos, y estaremos más que felices de ayudarte.

TacoTranslate te permite localizar automáticamente tus aplicaciones React rápida y fácilmente a cualquier idioma y desde cualquier idioma. ¡Comienza hoy!