Traduce una aplicación de Next.js Pages
Carga los mensajes traducidos de una página, renderízalos con el contenedor de Pages y agrega un selector de idioma y enlaces alternativos.
Una ruta de Next.js Pages ya resuelve el idioma de cada solicitud. @lingo.dev/react-next usa ese idioma para proporcionar mensajes a React y mantener los datos de la página junto con el texto traducido. Esta guía muestra cómo renderizar una página Acerca de en inglés y francés y conservar la selección de rutas cuando el JSONC traducido ha perdido sus metadatos.
Usa una aplicación de Pages existente con React 19. El paquete declara Next.js 13+ y React 18/19 como dependencias pares, pero el proveedor actual en tiempo de ejecución usa la sintaxis abreviada de contexto de React 19. Sus exportaciones son /pages, /pages/client y /pages/server; no tiene una exportación raíz ni un punto de entrada para App Router.
Configura los idiomas y el contenedor de la aplicación #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latestAgrega i18n a tu next.config.mjs existente sin cambiar el resto de la configuración:
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};En pages/_app.tsx, envuelve la aplicación:
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);El contenedor lee pageProps.__lingoMessages, resuelve el idioma activo de Next y proporciona LingoProvider. La configuración de i18n de Next determina la política de URL; la ruta predeterminada en inglés normalmente no lleva prefijo.
Escribe la página y carga sus mensajes #
Primero, agrega la función loadMatchedMessages de carga de catálogos como lib/catalog.ts. Esta función valida el JSONC con valores de tipo cadena y vincula los valores de destino con las claves de origen activas.
Luego, crea pages/about.tsx:
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}Este predicado conserva las entradas de la propia página y los mensajes de los componentes compartidos. Elimina las extensiones y los sufijos antiguos de números de línea de los metadatos de origen. Si la página está en src/pages/about.tsx, ajusta tanto la ruta de importación como la comparación de rutas para que coincidan.
El cargador personalizado falla de forma deliberada cuando falta un archivo obligatorio o su formato es incorrecto. Así, la compilación no puede reemplazar silenciosamente el catálogo esperado en francés por el contenido de respaldo en inglés. Las claves de destino individuales que faltan siguen ausentes y usan el mecanismo habitual de respaldo en tiempo de ejecución.
Extrae, traduce y abre ambas rutas #
Ejecuta npx lingo extract --src pages --source-locale en desde la raíz del proyecto. Para configurar un nuevo proyecto de Lingo.dev, ejecuta:
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitSi el proyecto ya está configurado, conserva su vinculación y las demás opciones de archivo. Después de la extracción, completa las actualizaciones habituales de los idiomas de destino existentes, recupéralas y revísalas. Luego, agrega fr y completa el contenido faltante sin cambiar esa revisión de origen. Carga de catálogos detalla los pasos de configuración y Agrega un idioma explica el orden que debes seguir. Si los componentes compartidos están fuera de pages, realiza la extracción desde un directorio que contenga todas las llamadas de mensajes, u organízalos bajo un árbol común de src y usa --src src.
Después de recuperar locales/fr.jsonc, ejecuta el comando habitual de desarrollo o compilación de Next. Abre /about y /fr/about. La primera ruta usa el texto de origen en inglés; la segunda usa la traducción al francés para la misma clave de encabezado. Comprueba el texto real en francés y el respaldo con el texto de origen para una entrada que hayas dejado ausente de forma deliberada.
Carga integrada de propiedades estáticas #
Cuando cada archivo de idioma conserva los metadatos correctos de @src y @orphan, la función auxiliar del servidor puede reemplazar el getStaticProps personalizado anterior:
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? }) lee rutas fijas de locales/<locale>.jsonc relativas al directorio de trabajo. Filtra las entradas huérfanas y las de otras páginas, y trata como compartidos los orígenes que no corresponden a páginas y las entradas sin @src. La traducción general de JSONC conserva las marcas @orphan, pero elimina los comentarios @src. Por eso, para esa salida, usa el procedimiento anterior de vinculación por claves de origen; la función auxiliar no restaura los metadatos.
Si falta un archivo, se devuelve {} con una advertencia en desarrollo; si el archivo existe pero no es válido, puede generar una excepción. Un manejador asíncrono opcional agrega propiedades o devuelve un resultado de redirección o de página no encontrada. Los resultados exitosos conservan campos como revalidate y agregan __lingoMessages. Sus tipos públicos usan el contexto y los resultados de propiedades estáticas; no asumas que cualquier manejador de solicitudes del lado del servidor tiene el mismo contrato. Sobrescribir las rutas de los catálogos mediante la CLI tampoco cambia este directorio fijo del cargador.
Expande las rutas estáticas dinámicas #
Para una ruta dinámica, la función auxiliar del servidor expande cada entrada de parámetros a todos los idiomas configurados en Next:
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});El valor de respaldo predeterminado es "blocking"; también se admiten false y true. La expansión no traduce los slugs ni garantiza que cada catálogo contenga los mensajes de la ruta.
Cambia de idioma y agrega enlaces alternativos #
Renderiza un selector debajo del contenedor de la aplicación:
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}Reemplaza el origen del ejemplo por el origen absoluto del sitio en producción. LingoHead genera enlaces alternativos para los idiomas configurados y x-default, sin el prefijo del idioma predeterminado. No genera metadatos canónicos ni de Open Graph. Revisa las URL resultantes según tu política de rutas y consultas.
La función de cambio escribe NEXT_LOCALE con una vigencia de un año en / con SameSite=Lax y luego navega con el enrutador de Next usando el asPath actual. Proporciona los idiomas configurados, como se muestra arriba; la función no comprueba las entradas arbitrarias contra la lista de idiomas admitidos.
Establece los atributos iniciales del documento #
Establece los atributos iniciales en pages/_document.tsx sin alterar las personalizaciones existentes del documento:
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp establece la dirección después de los cambios de idioma y genera un script RTL en línea para el renderizado inicial, pero no establece lang. El efecto _app anterior actualiza lang durante la navegación; el documento personalizado proporciona ambos atributos iniciales. Una política estricta de seguridad de contenido puede bloquear el script en línea del contenedor, que no ofrece una opción de nonce. El documento personalizado proporciona la dirección inicial sin depender de ese script. Revisa también la política de scripts de la aplicación durante la navegación.
Por último, comprueba la hidratación con el mismo catálogo y valores de tiempo explícitos. Verifica que, al cambiar de idioma, los mensajes y los atributos del documento se actualicen al mismo tiempo.