Cómo internacionalizar tu aplicación Next.js usando next-intl en 2026

.├── global.ts├── locales│   ├── en│   │  ├── common.json│   │  └── about.json│   ├── fr│   │  ├── common.json│   │  └── about.json│   └── es│      ├── common.json│      └── about.json└── src # Src es opcional    ├── proxy.ts    ├── app    │   ├── i18n.ts    │   └── [locale]    │       ├── layout.tsx    │       ├── (home) # / (Grupo de rutas para no saturar todas las páginas con recursos de home)    │       │   ├── layout.tsx    │       │   └── page.tsx    │       └── about # /about    │           ├── layout.tsx    │           └── page.tsx    └── components        ├── ClientComponent.tsx        └── ServerComponent.tsx

npm install next-intl

import { notFound } from "next/navigation";import createMiddleware from "next-intl/middleware";import { createNavigation } from "next-intl/navigation";// Define los locales soportados con seguridad de tiposexport const locales = ["en", "fr", "es"] as const;export type Locale = (typeof locales)[number];export const defaultLocale: Locale = "en";export function isRTL(locale: Locale | (string & {})) {  // Devuelve true si el locale es un idioma que se escribe de derecha a izquierda  return /^(ar|fa|he|iw|ur|ps|sd|ug|yi|ckb|ku)(-|$)/i.test(locale);}// Carga mensajes dinámicamente por locale para habilitar code-splitting// Promise.all carga los namespaces en paralelo para mejor rendimientoasync function loadMessages(locale: Locale) {  // Carga solo los namespaces que tu layout/páginas necesitan  const [common, home, about] = await Promise.all([    import(`../locales/${locale}/common.json`).then((m) => m.default),    import(`../locales/${locale}/home.json`).then((m) => m.default),    import(`../locales/${locale}/about.json`).then((m) => m.default),    // ... Los futuros archivos JSON deberían añadirse aquí  ]);  return { common, home, about } as const;}// Ayudante para generar URLs localizadas (por ejemplo, /about vs /fr/about)export function localizedPath(locale: string, path: string) {  return locale === defaultLocale ? path : `/${locale}${path}`;}// getRequestConfig se ejecuta en cada solicitud y proporciona mensajes a los componentes del servidor// Aquí es donde next-intl se conecta con el renderizado del lado servidor de Next.jsexport default async function getRequestConfig({  requestLocale,}: {  requestLocale: Promise<string | undefined>;}) {  const requested: Locale = ((await requestLocale) as Locale) ?? defaultLocale;  if (!locales.includes(requested)) notFound();  return {    locale: requested,    messages: await loadMessages(requested),  };}export function getCookie(locale: Locale) {  return [    `NEXT_LOCALE=${locale}`,    "Path=/",    `Max-Age=${60 * 60 * 24 * 365}`, // 1 año    "SameSite=Lax",  ].join("; ");}const routingOptions = {  locales,  defaultLocale,  localePrefix: "as-needed", // Cambiar ruta /en/... a /...  // Opcional: rutas localizadas  // pathnames: {  //   '/': '/',  //   '/about': {en: '/about', fr: '/a-propos', es: '/acerca-de'},  //   '/blog/[slug]': '/blog/[slug]'  // }  //  localeDetection: true, // evitar redirecciones de "/" a "/en" desde cookie} as const;export const { Link, redirect, usePathname, useRouter, getPathname } =  createNavigation(routingOptions);export const proxy = createMiddleware(routingOptions);

import type { ReactNode } from "react";import { locales } from "@/i18n";import { getLocaleDirection, setRequestLocale } from "next-intl/server";// Pre-generar páginas estáticas para todas las locales en tiempo de compilación (SSG)// Esto mejora el rendimiento y el SEOexport function generateStaticParams() {  return locales.map((locale) => ({ locale }));}export default function LocaleLayout({  children,  params,}: {  children: ReactNode;  params: Promise<{ locale: string }>;}) {  // En Next.js App Router, params es una Promise (se puede await)  // Esto permite que los segmentos de ruta dinámicos se resuelvan de forma asíncrona  const { locale } = await params;  // Crítico: setRequestLocale indica a next-intl qué locale usar para esta solicitud  // Sin esto, getTranslations() no sabrá qué locale usar en los componentes del servidor  setRequestLocale(locale);  // Obtener la dirección del texto (LTR/RTL) para el renderizado correcto del HTML  const dir = getLocaleDirection(locale);  return (    <html lang={locale} dir={dir}>      <body>{children}</body>    </html>  );}

import { getTranslations, getMessages, getFormatter } from "next-intl/server";import { NextIntlClientProvider } from "next-intl";import pick from "lodash/pick";import ServerComponent from "@/components/ServerComponent";import ClientComponent from "@/components/ClientComponent";export default async function AboutPage({  params,}: {  params: Promise<{ locale: string }>;}) {  const { locale } = await params;  // Los mensajes se cargan del lado del servidor. Solo se envía al cliente lo necesario.  // Esto minimiza el paquete de JavaScript enviado al navegador  const messages = await getMessages();  const clientMessages = pick(messages, ["common", "about"]);  // Traducciones/formateo estrictamente del lado del servidor  // Estos se ejecutan en el servidor y pueden pasarse como props a los componentes  const tAbout = await getTranslations("about");  const tCounter = await getTranslations("about.counter");  const format = await getFormatter();  const initialFormattedCount = format.number(0);  return (    // NextIntlClientProvider hace que las traducciones estén disponibles para los componentes cliente    // Solo pasa los namespaces que tus componentes cliente realmente usan    <NextIntlClientProvider locale={locale} messages={clientMessages}>      <main>        <h1>{tAbout("title")}</h1>        <ClientComponent />        <ServerComponent          formattedCount={initialFormattedCount}          label={tCounter("label")}          increment={tCounter("increment")}        />      </main>    </NextIntlClientProvider>  );}

{  "welcome": "Welcome",  "greeting": "Hello, world!"}

{  "welcome": "Bienvenue",  "greeting": "Bonjour le monde!"}

{  "title": "About",  "description": "About page description",  "counter": {    "label": "Counter",    "increment": "Increment"  }}

{  "title": "À propos",  "description": "Description de la page À propos",  "counter": {    "label": "Compteur",    "increment": "Incrémenter"  }}

import { getTranslations, getMessages, getFormatter } from "next-intl/server";import { NextIntlClientProvider } from "next-intl";import pick from "lodash/pick";import ServerComponent from "@/components/ServerComponent";import ClientComponent from "@/components/ClientComponent";export default async function AboutPage({  params,}: {  params: Promise<{ locale: string }>;}) {  const { locale } = await params;  // Los mensajes se cargan del lado del servidor. Solo se envía al cliente lo que se necesita.  // Esto minimiza el paquete de JavaScript enviado al navegador  const messages = await getMessages();  const clientMessages = pick(messages, ["common", "about"]);  // Traducciones/formateo estrictamente del lado del servidor  // Estos se ejecutan en el servidor y pueden pasarse como props a los componentes  const tAbout = await getTranslations("about");  const tCounter = await getTranslations("about.counter");  const format = await getFormatter();  const initialFormattedCount = format.number(0);  return (    // NextIntlClientProvider hace que las traducciones estén disponibles para los componentes cliente    // Solo pasa los namespaces que tus componentes cliente realmente usan    <NextIntlClientProvider locale={locale} messages={clientMessages}>      <main>        <h1>{tAbout("title")}</h1>        <ClientComponent />        <ServerComponent          formattedCount={initialFormattedCount}          label={tCounter("label")}          increment={tCounter("increment")}        />      </main>    </NextIntlClientProvider>  );}

"use client";import React, { useState } from "react";import { useTranslations, useFormatter } from "next-intl";const ClientComponent = () => {  // Alcance directamente al objeto anidado  // useTranslations/useFormatter son hooks que leen del contexto NextIntlClientProvider  // Solo funcionan si el componente está envuelto en NextIntlClientProvider  const t = useTranslations("about.counter");  const format = useFormatter();  const [count, setCount] = useState(0);  return (    <div>      <p>{format.number(count)}</p>      <button        aria-label={t("label")}        onClick={() => setCount((count) => count + 1)}      >        {t("increment")}      </button>    </div>  );};

// Los componentes del servidor anidados dentro de componentes cliente deben ser síncronos// React no puede serializar funciones asíncronas a través del límite servidor/cliente// Solución: pre-calcular traducciones/formateos en el padre y pasarlos como propstype ServerComponentProps = {  formattedCount: string;  label: string;  increment: string;};const ServerComponent = ({  formattedCount,  label,  increment,}: ServerComponentProps) => {  return (    <div>      <p>{formattedCount}</p>      <button aria-label={label}>{increment}</button>    </div>  );};

"use client";import Link from "next/link";import { usePathname } from "next/navigation";import { useLocale } from "next-intl";import { defaultLocale, getCookie, type Locale, locales } from "@/i18n";const getLocaleLabel = (locale: Locale): string => {  try {    const displayNames = new Intl.DisplayNames([locale], { type: "language" });    return displayNames.of(locale) ?? locale.toUpperCase();  } catch {    return locale.toUpperCase();  }};const localeFlags: Record<Locale, string> = {  en: "🇬🇧",  fr: "🇫🇷",  es: "🇪🇸",};export default function LocaleSwitcher() {  const activeLocale = useLocale();  const pathname = usePathname();  // Eliminar el prefijo de la localidad del pathname para obtener la ruta base  const getBasePath = (path: string) => {    for (const locale of locales) {      if (path.startsWith(`/${locale}`)) {        return path.slice(locale.length + 1) || "/";      }    }    return path;  };  const basePath = getBasePath(pathname);  return (    <nav aria-label="Selector de idioma">      <div>        {(locales as readonly Locale[]).map((locale) => {          const isActive = locale === activeLocale;          // Construir el href según si es el locale por defecto          const href =            locale === defaultLocale ? basePath : `/${locale}${basePath}`;          return (            <Link              key={locale}              href={href}              aria-current={isActive ? "page" : undefined}              onClick={() => {                document.cookie = getCookie(locale);              }}            >              <span>{localeFlags[locale]}</span>              <span>{getLocaleLabel(locale)}</span>              <span>{locale.toUpperCase()}</span>            </Link>          );        })}      </div>    </nav>  );}

import { Link } from "@/i18n";return <Link href="/about">t("about.title")</Link>;

"use server";import { getLocale } from "next-intl/server";export async function getCurrentLocale() {  return getLocale();}export async function handleContactForm(formData: FormData) {  const locale = await getCurrentLocale();  // Usa la locale para seleccionar plantillas, etiquetas de analíticas, etc.  console.log(`Formulario de contacto recibido desde la locale ${locale}`);}

import type { Metadata } from "next";import { locales, defaultLocale, localizedPath } from "@/i18n";import { getTranslations } from "next-intl/server";// generateMetadata se ejecuta para cada locale, generando metadatos amigables para SEO// Esto ayuda a los motores de búsqueda a entender las versiones en idiomas alternativosexport async function generateMetadata({  params,}: {  params: { locale: string };}): Promise<Metadata> {  const { locale } = params;  const t = await getTranslations({ locale, namespace: "about" });  const url = "/about";  const languages = Object.fromEntries(    locales.map((locale) => [locale, localizedPath(locale, url)])  );  return {    title: t("title"),    description: t("description"),    alternates: {      canonical: localizedPath(locale, url),      languages: { ...languages, "x-default": url },    },  };}// ... Resto del código de la página

import type { MetadataRoute } from "next";import { defaultLocale, locales } from "@/i18n";const origin = "https://example.com";const formatterLocalizedPath = (locale: string, path: string) =>  locale === defaultLocale ? `${origin}${path}` : `${origin}/${locale}${path}`;/** * Obtiene un mapa de todos los locales y sus rutas localizadas * * Ejemplo de salida: * { *   "en": "https://example.com", *   "fr": "https://example.com/fr", *   "es": "https://example.com/es", *   "x-default": "https://example.com" * } */const getLocalizedMap = (path: string) =>  Object.fromEntries([    ...locales.map((locale) => [locale, formatterLocalizedPath(locale, path)]),    ["x-default", formatterLocalizedPath(defaultLocale, path)],  ]);// Generar sitemap con todas las variantes de locales para un mejor SEO// El campo alternates informa a los motores de búsqueda sobre las versiones de idiomaexport default function sitemap(): MetadataRoute.Sitemap {  return [    {      url: formatterLocalizedPath(defaultLocale, "/"),      lastModified: new Date(),      changeFrequency: "monthly",      priority: 1.0,      alternates: { languages: getLocalizedMap("/") },    },    {      url: formatterLocalizedPath(defaultLocale, "/about"),      lastModified: new Date(),      changeFrequency: "monthly",      priority: 0.7,      alternates: { languages: getLocalizedMap("/about") },    },  ];}

import type { MetadataRoute } from "next";import { locales, defaultLocale } from "@/i18n";const origin = "https://example.com";// Genera rutas para todos los locales (por ejemplo, /admin, /fr/admin, /es/admin)const withAllLocales = (path: string) => [  path,  ...locales    .filter((locale) => locale !== defaultLocale)    .map((locale) => "/" + locale + path),];export default function robots(): MetadataRoute.Robots {  const disallow = [    ...withAllLocales("/dashboard"),    ...withAllLocales("/admin"),  ];  return {    rules: { userAgent: "*", allow: ["/"], disallow },    host: origin,    sitemap: origin + "/sitemap.xml",  };}

import { proxy } from "@/i18n";// Middleware que se ejecuta antes de las rutas, manejando la detección y el enrutamiento de la locale// localeDetection: true usa el encabezado Accept-Language para detectar automáticamente la localeexport default proxy;export const config = {  // Omitir API, internals de Next y assets estáticos  // Regex: coincide con todas las rutas excepto las que comienzan con api, _next, o que contienen un punto (archivos)  matcher: ["/((?!api|_next|.*\\..*).*)"],};

import type { locales } from "@/i18n";type Messages = {  common: typeof import("./locales/en/common.json");  home: typeof import("./locales/en/home.json");  about: typeof import("./locales/en/about.json");  // ... Los futuros archivos JSON también deben añadirse aquí};declare module "next-intl" {  interface AppConfig {    Locale: (typeof locales)[number];    Messages: Messages;  }}