Cómo implementar la internacionalización en una aplicación Next.js que utiliza 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 principales formas de lograr esto es mediante la internacionalización (i18n), que le permite adaptar su aplicación a distintos idiomas, monedas y formatos de fecha.

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

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

Paso 1: Instalar una biblioteca de i18n

Para implementar la internacionalización en tu aplicación Next.js, primero elegiremos una biblioteca i18n. Hay varias bibliotecas populares, incluyendo next-intl. En este ejemplo, sin embargo, usaremos TacoTranslate.

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

Instálalo usando npm en tu terminal:

npm install tacotranslate

Paso 2: Crea una cuenta gratuita de TacoTranslate

Ahora que tienes el módulo instalado, es hora 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.

En 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 añadirlas 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 en 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 predeterminado que se usará como respaldo. En este ejemplo lo configuraremos 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: Configurar TacoTranslate

Para integrar TacoTranslate con su aplicación, necesitará crear un cliente usando las claves de la API indicadas anteriormente. Por ejemplo, cree 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 volver a utilizarlo 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>
	);
}

Observa el 'use client'; que indica que se trata de un componente del lado del cliente.

Con el proveedor de contexto ya listo para usarse, crea un archivo llamado /app/[locale]/layout.tsx, el layout raíz de nuestra aplicación. Ten en cuenta que esta ruta contiene 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 Dynamic Route parámetro [locale] para obtener las traducciones de ese idioma. Además, generateStaticParams se asegura de que todos los códigos de locales que hayas activado 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!" />
	);
}

Tenga en cuenta la variable revalidate que indica a Next.js que reconstruya la página después de 60 segundos y mantenga sus traducciones actualizadas.

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

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

Para configurar el renderizado del lado del servidor, cree o modifique /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};
};

Modifica la comprobación isProduction para que se ajuste 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.

Para garantizar que el enrutamiento y las redirecciones 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. Consulta el código de ejemplo completo para obtener ideas sobre cómo hacerlo.

Paso 5: ¡Despliega y prueba!

¡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 así, 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 infle tu proyecto de traducción al añadir nuevas cadenas no relacionadas.

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 Pages 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!