Cómo implementar la internacionalización en una aplicación Next.js que utiliza el App Router
Haz que tu aplicación React sea más accesible y alcanza nuevos mercados con la internacionalización (i18n).
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 diferentes 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 artículo, exploraremos cómo agregar 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 utilizan 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 su 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 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 en 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 su 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 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 idioma predeterminado de reserva. En este ejemplo, lo estableceremos enen
para inglés.TACOTRANSLATE_ORIGIN
: La “carpeta” donde se almacenarán tus cadenas, como la URL de tu sitio web. Más información sobre los orígenes aquí.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
Paso 3: Configuración de TacoTranslate
Para integrar TacoTranslate con tu aplicación, necesitarás crear un cliente usando 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 volver a usarlo más adelante. getLocales
es solo una función utilitaria con 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>
);
}
Tenga en cuenta 'use client';
que indica que este es 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 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 es que estamos usando nuestro parámetro Dynamic Route
[locale]
para obtener las traducciones de ese idioma. Además, generateStaticParams
se asegura de que todos los códigos de locale 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!" />
);
}
Ten en cuenta 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 admite el renderizado del lado del servidor. Esto mejora considerablemente la experiencia del usuario al mostrar el contenido traducido de inmediato, en lugar de un destello de contenido sin traducir al principio. Además, podemos evitar las solicitudes de red desde el cliente, porque ya disponemos de las traducciones necesarias 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 verificación isProduction
para adaptarla a tu configuración. Si es true
, TacoTranslate mostrará la clave pública de la API. Si estamos en un entorno local, de prueba o 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 asegurarnos de 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. 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 agregues 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 ser traducidas. Recomendamos disponer de un entorno de staging cerrado y seguro donde puedas probar tu aplicación de producción con una clave de API de ese tipo, añadiendo nuevas cadenas antes de ponerla en marcha. Esto evitará que cualquiera cualquiera robe tu clave secreta de la API y, potencialmente, que se sobrecargue tu proyecto de traducción con 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!