Traduce una aplicación Next.js Pages

Carga los mensajes traducidos de una página, muéstralos a través del componente contenedor de Pages y añade un selector de idioma y enlaces alternativos.

Cada ruta de Next.js Pages determina el idioma de la petición. @lingo.dev/react-next utiliza ese idioma para proporcionar los mensajes de React y mantener juntos los datos de la página y 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.

Utiliza una aplicación Pages existente con React 19. El paquete declara Next.js 13+ y React 18/19 como dependencias entre pares, pero el proveedor actual utiliza la sintaxis abreviada de contexto de React 19 en tiempo de ejecución. Sus exportaciones son /pages, /pages/client y /pages/server; no dispone de una exportación raíz ni de un punto de entrada para App Router.

Configura los idiomas y el componente contenedor de la aplicación #

sh
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@latest

Añade i18n a tu next.config.mjs existente sin modificar los demás ajustes:

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

En pages/_app.tsx, envuelve la aplicación:

tsx
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 componente contenedor lee pageProps.__lingoMessages, determina 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, añade como lib/catalog.ts la función loadMatchedMessages de carga de catálogos. Esta función valida que los valores del JSONC sean cadenas y vincula los valores de destino con las claves de origen activas.

Después, crea pages/about.tsx:

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 antiguos sufijos de número de línea de los metadatos de origen. Si la página está en src/pages/about.tsx, actualiza tanto la ruta de importación como la comparación de rutas para que coincidan con esa ubicación.

El cargador personalizado falla deliberadamente cuando falta un archivo obligatorio o su formato no es válido. Así, la compilación no puede sustituir silenciosamente el catálogo esperado en francés por el inglés como alternativa. Las claves individuales que faltan en el destino siguen ausentes y recurren al mecanismo habitual de alternativa 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:

sh
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Si el proyecto ya está configurado, conserva su vinculación y las demás opciones de archivo. Tras la extracción, completa las actualizaciones habituales de los idiomas de destino existentes, descárgalas y revísalas. Después, añade fr y completa los mensajes pendientes sin cambiar esa revisión de origen. Carga de catálogos detalla los pasos de configuración y Añadir 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 a mensajes, u organízalos en un árbol común src y utiliza --src src.

Tras descargar locales/fr.jsonc, ejecuta el comando habitual de desarrollo o compilación de Next. Abre /about y /fr/about. La primera ruta utiliza el texto de origen en inglés; la segunda, la traducción al francés de la misma clave de encabezado. Comprueba el texto que se muestra en francés y que se utiliza el texto de origen como alternativa cuando falta una entrada deliberadamente.

Carga integrada de propiedades estáticas #

Si cada archivo de idioma conserva los metadatos correctos de @src y @orphan, la función auxiliar del servidor puede sustituir el getStaticProps personalizado anterior:

ts
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 considera compartidos los archivos de origen 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 tanto, para ese resultado, utiliza el procedimiento anterior de vinculación por claves de origen; la función auxiliar no restaura los metadatos.

Si falta un archivo, devuelve {} y muestra una advertencia en desarrollo; si un archivo existente no es válido, puede lanzar una excepción. Un controlador asíncrono opcional añade propiedades o devuelve un resultado de redirección o de página no encontrada. Los resultados satisfactorios conservan campos como revalidate y añaden __lingoMessages. Sus tipos públicos utilizan el contexto y los resultados de propiedades estáticas; no des por hecho que cualquier controlador de peticiones del lado del servidor tenga el mismo contrato. Las modificaciones de la ruta del catálogo mediante la CLI tampoco cambian este directorio fijo del cargador.

Amplía las rutas estáticas dinámicas #

Para una ruta dinámica, la función auxiliar del servidor amplía cada entrada de parámetros a todos los idiomas configurados en Next:

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

El valor predeterminado para el comportamiento alternativo es "blocking"; también se admiten false y true. La ampliación no traduce los segmentos de URL ni garantiza que todos los catálogos contengan los mensajes de la ruta.

Cambia de idioma y añade enlaces alternativos #

Renderiza un selector dentro del componente contenedor de la aplicación:

tsx
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>
  );
}

Sustituye 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 para comprobar que se ajustan a tu política de rutas y parámetros de consulta.

La función de cambio escribe NEXT_LOCALE con una vigencia de un año en / y con SameSite=Lax. Después, navega con el enrutador de Next utilizando el asPath actual. Proporciona los idiomas configurados, como en el ejemplo anterior; la función no valida entradas arbitrarias frente a la lista de idiomas admitidos.

Establece los atributos iniciales del documento #

Establece los atributos iniciales en pages/_document.tsx sin modificar las personalizaciones existentes del documento:

tsx
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 tras cada cambio 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 de seguridad de contenido estricta puede bloquear el script en línea del componente contenedor, que no ofrece ninguna opción de nonce. El documento personalizado proporciona la dirección inicial sin depender de ese script. Comprueba 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 a la vez.