Traduce una aplicación con App Router de Next.js
Sirve cada página con un prefijo de idioma, redirige las rutas sin prefijo y renderiza componentes de servidor y de cliente traducidos con @lingo.dev/react-next.
En App Router, cada idioma tiene su propio prefijo de URL, incluido el idioma de origen: los usuarios acceden a /en/pricing y /de/pricing. @lingo.dev/react-next lee el idioma de un segmento de ruta app/[locale], carga el catálogo de ese idioma en el servidor y proporciona los mismos mensajes a los componentes de servidor y de cliente. Esta guía añade alemán y francés a una aplicación en inglés.
Usa Next.js 16 o posterior con React 19; los puntos de entrada leen el idioma mediante next/root-params. Instala los paquetes:
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latestDefine los idiomas #
Crea i18n.ts junto a app/ (src/i18n.ts si la aplicación usa src/):
import { createLocaleRouter } from "@lingo.dev/locale-router";
export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });
export const localePath = (pathname: string, locale: string) =>
locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);Enumera los idiomas en .lingo/config.json y establece el idioma de origen como defaultLocale. exclude indica los segmentos iniciales de ruta que no llevan prefijo, como los controladores de rutas dentro de app/api/. No pases slugs: el segmento de URL de cada idioma debe ser su etiqueta en minúsculas (/pt-br para pt-BR), porque getLingo() determina el idioma únicamente a partir de ese segmento. Un slug personalizado hace que el proveedor lance un error que indica dicho slug. El proxy y los componentes de servidor y de cliente importan este archivo, así que no incluyas otras importaciones en él.
Redirige las rutas sin prefijo #
Crea proxy.ts junto a app/:
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";
export const proxy = lingoProxy(locales);
export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };lingoProxy(locales) gestiona dos tipos de solicitudes:
| Solicitud | Respuesta |
|---|---|
Un primer segmento que identifica un idioma de una forma distinta a su slug, como /DE/about, /de-AT o /de_DE | 301 a la dirección canónica. |
Una ruta localizada sin idioma, como /about | 307 al idioma negociado a partir de Accept-Language, con Cache-Control: private, no-store y Vary: Accept-Language. |
| Cualquier otro caso | undefined. |
Las redirecciones conservan la cadena de consulta y el basePath de la aplicación. Next.js lee el patrón de coincidencia durante la compilación, así que mantenlo como un valor literal y asegúrate de que su api esté sincronizado con exclude. Si la aplicación ya tiene un proxy, llama primero a lingoProxy y continúa con tu propia lógica cuando devuelva undefined. Un middleware.ts es el mismo archivo con su nombre anterior; renómbralo como proxy.ts y cambia el nombre de su función a proxy.
Mueve las rutas al segmento de idioma #
Mueve el diseño raíz y todas las páginas a app/[locale]/, un nivel de carpeta por debajo. app/[locale]/layout.tsx pasa a ser el diseño raíz y deja de haber un app/layout.tsx. Los controladores de rutas dentro de app/api/, globals.css, los iconos, robots.ts y sitemap.ts se quedan donde están. Elimina cualquier clave i18n de next.config; App Router no la lee.
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";
export function generateStaticParams() {
return lingoStaticParams(locales);
}
export default async function RootLayout({ children }: { children: ReactNode }) {
const l = await getLingo();
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoAppProvider locales={locales}>{children}</LingoAppProvider>
</body>
</html>
);
}lingoStaticParams devuelve un { locale } por idioma, por lo que la compilación prerenderiza cada página una vez por idioma. LingoAppProvider devuelve un error 404 si el idioma no está en la lista. No añadas export const dynamicParams = false: Next.js lo rechaza cuando cacheComponents está activado.
Traduce los componentes de servidor y de cliente #
Los componentes de servidor, las páginas, los diseños y generateMetadata llaman a await getLingo() desde @lingo.dev/react-next/app/server. Los componentes de cliente llaman a useLingo() desde @lingo.dev/react; LingoAppProvider les proporciona el idioma y el catálogo. En ninguno de los dos casos hace falta pasarles el idioma.
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";
export default async function Home() {
const l = await getLingo();
return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}Un componente de servidor puede recibir l como propiedad de su componente padre de servidor, pero nunca pases l a un componente de cliente: las funciones no pueden pasar del servidor al cliente. Llamar a getLingo() fuera de app/[locale]/ provoca un error porque no encuentra ningún segmento [locale].
Añade metadatos #
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
export async function generateMetadata() {
const l = await getLingo();
return {
title: l.text("Pricing", { context: "Title of the pricing page" }),
...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
};
}lingoMetadata({ locales, pathname, origin, ogLocale? }) devuelve alternates.canonical, alternates.languages para cada idioma además de x-default, y openGraph.url y openGraph.locale. Pasa la ruta de la página sin el prefijo de idioma, la cadena de consulta ni el fragmento; una ruta dinámica la construye a partir de sus parámetros. Sustituye el origen del ejemplo por el de tu sitio. Política de URL por idioma explica lingoHead, que construye los valores, y la opción ogLocale para sobrescribirlos.
Crea enlaces y cambia de idioma #
Añade a cada enlace interno su prefijo con localePath("/pricing", l.locale) de i18n.ts. l.locale es una cadena de texto, así que localePath la restringe a uno de los idiomas del enrutador antes de que locales.prefix añada el prefijo. Un enlace sin prefijo llega al proxy, que redirige al idioma del navegador en lugar de al de la página. Lo mismo se aplica a redirect(), router.push() y a las acciones de formulario que indican una ruta.
"use client";
import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";
export function LocaleSwitcher() {
const options = useLocaleSwitch(locales);
return (
<nav aria-label="Language">
{options.map((option) => (
<Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
{option.label}
</Link>
))}
</nav>
);
}useLocaleSwitch(locales) devuelve un { locale, label, href, current } por idioma: la página actual en ese idioma, el nombre del idioma en su propia lengua y si es el idioma actual. La cadena de consulta se añade después de la hidratación, por lo que una página que renderiza el selector sigue siendo estática. Al seguir un enlace, se vuelve a renderizar el diseño, que carga el catálogo del nuevo idioma.
Extrae y carga los catálogos #
El servidor lee locales/<locale>.jsonc en la carpeta desde la que se ejecuta next, mediante fs, así que deja i18n.messagesPath en su valor predeterminado, locales. Descarta las entradas huérfanas y vuelve a leer el archivo en cada solicitud, por lo que next dev sirve el catálogo modificado en la siguiente solicitud. Si falta el archivo, se obtiene un catálogo vacío y, durante el desarrollo, una advertencia; un archivo con un formato incorrecto o un valor que no sea una cadena provoca un error que indica el nombre del archivo. En producción, el idioma de origen no envía ningún catálogo al navegador porque su texto se usa como alternativa.
Si app/ está en la raíz del proyecto y no hay una carpeta src/, establece "i18n": { "src": "." } en .lingo/config.json para que la extracción examine app/ y components/. La extracción omite node_modules y las carpetas cuyo nombre empieza por un punto, como .next. Para una configuración nueva:
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitEstablece i18n.src después de init, que reescribe la sección i18n. En un monorepositorio, .lingo/config.json está en la raíz del repositorio y sus rutas parten de ahí, así que messagesPath es la carpeta de la aplicación seguida de locales, como apps/web/locales; consulta el mapa i18n de aplicaciones con nombre en Configuración de la CLI. El servidor sigue leyendo locales/ en la carpeta de la propia aplicación.
Después de next build y next start, abre / y comprueba que redirige a un idioma. A continuación, abre /de y comprueba que el texto en alemán aparece en el HTML.
Entorno de ejecución #
Las páginas prerenderizadas funcionan en cualquier servicio de alojamiento. Una página renderizada bajo demanda lee su catálogo del disco, por lo que necesita el entorno de ejecución de Node.js; Cloudflare Workers y el entorno de ejecución Edge no pueden leerlo.
Exportaciones #
| Punto de entrada | Exportaciones |
|---|---|
@lingo.dev/react-next/app/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) y el tipo LocaleOption. |
@lingo.dev/react-next/app/proxy | lingoProxy(locales). |
Los agentes de programación pueden seguir lingo agent-guide react-next-app una vez instalado el paquete, y lingo agent-guide react-next-migrate para migrar desde next-intl. Consulta Configurar con un agente de programación.