Traduce una aplicación de Next.js con App Router
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 lectores visitan /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 agrega alemán y francés a una aplicación en inglés.
Usa Next.js 16 o una versión 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);Lista los idiomas en .lingo/config.json y establece el idioma de origen como defaultLocale. exclude especifica los primeros segmentos de ruta que no llevan prefijo, como los controladores de ruta en 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 del segmento. Un slug personalizado hace que el proveedor lance un error que lo identifica. El proxy y los componentes de servidor y de cliente importan este archivo, así que no incluyas otras importaciones.
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) procesa dos tipos de solicitudes:
| Solicitud | Respuesta |
|---|---|
Un primer segmento que identifica un idioma con un valor distinto de 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 a 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 cada página un nivel hacia abajo en la estructura de carpetas, dentro de app/[locale]/. app/[locale]/layout.tsx se convierte en el diseño raíz y ya no queda ningún app/layout.tsx. Los controladores de ruta en app/api/, globals.css, los íconos, 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 prerrenderiza cada página una vez por idioma. LingoAppProvider devuelve un 404 si el idioma no está en la lista. No agregues 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. Ninguno necesita recibir el idioma desde un componente superior.
// 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]/ genera un error porque no encuentra ningún segmento [locale].
Agrega 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 consulta ni el fragmento; una ruta dinámica la construye a partir de sus parámetros. Reemplaza 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 #
Agrega el prefijo a cada enlace interno con localePath("/pricing", l.locale) de i18n.ts. l.locale es una cadena de texto simple, así que localePath la restringe a uno de los idiomas del enrutador antes de que locales.prefix agregue el prefijo. Un enlace sin prefijo llega al proxy, que redirige al idioma del navegador en lugar del idioma de la página. Lo mismo se aplica a redirect(), router.push() y las acciones de formulario que especifican 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 ese mismo idioma y si es el idioma actual. La cadena de consulta se agrega 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 desde la carpeta en la que se ejecuta next, mediante fs, así que mantén 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 editado en la siguiente solicitud. Si falta el archivo, se obtiene un catálogo vacío y, en desarrollo, una advertencia; un archivo con formato incorrecto o un valor que no sea una cadena de texto genera un error que identifica el archivo. En producción, el idioma de origen no envía ningún catálogo al navegador porque su texto se usa como alternativa.
Cuando app/ está en la raíz del proyecto y no hay una carpeta src/, configura "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 con 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 --waitConfigura 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í, por lo que messagesPath es la carpeta de la aplicación más 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 verifica que redirija a un idioma; luego abre /de y comprueba que el texto en alemán aparezca en el HTML.
Entorno de ejecución #
Las páginas prerrenderizadas 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 Configura con un agente de programación.