Localiza Markdoc con Next.js

Enruta, carga, traduce y renderiza documentos Markdoc para cada idioma junto con catálogos de interfaz independientes en una aplicación Next.js con App Router.

Un artículo traducido debe encajar con la página que lo rodea. En un sitio Next.js, el idioma de la ruta puede determinar tanto el documento Markdoc como un catálogo de interfaz independiente para la navegación. Esta guía conecta esos archivos con una página de App Router y después los traduce mediante la CLI.

Utiliza un proyecto existente de Next.js con App Router y Markdoc. El ejemplo lee archivos locales en el servidor y no depende de un adaptador de localización para React.

Elige una estructura de archivos por idioma #

Un proyecto de ejemplo puede agrupar los documentos y los catálogos de interfaz por idioma:

text
src/content/
  en/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
  es/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
src/app/[lang]/

Mantén los slugs estables cuando sean identificadores de contenido. Traducir un encabezado no obliga a cambiar el nombre de home.mdoc. Si decides localizar los slugs, mantén una correspondencia explícita para la navegación y los enlaces a otros idiomas; traducir el cuerpo del documento no crea esa correspondencia.

Comprueba que el idioma de la ruta y el slug del documento pertenezcan a conjuntos conocidos antes de construir una ruta del sistema de archivos. Decide cómo gestionar las traducciones que falten: devolver una respuesta de recurso no encontrado o recurrir explícitamente al idioma de origen. El ejemplo de página de inicio que aparece a continuación utiliza un nombre de documento fijo y devuelve una respuesta de recurso no encontrado si el idioma no está admitido o falta el archivo.

Selecciona el controlador de Markdoc y los metadatos visibles #

Instala y vincula la CLI desde la raíz del proyecto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo link

Conserva en .lingo/config.json los ID generados para la organización y el motor de localización y, después, configura la selección completa de archivos de origen:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [
    {
      "pattern": "src/content/en/pages/*.mdoc",
      "format": "markdoc",
      "translateFrontmatterFields": ["title", "description"]
    },
    {
      "pattern": "src/content/en/blog/*.mdoc",
      "format": "markdoc",
      "translateFrontmatterFields": ["title", "description"]
    },
    { "pattern": "src/content/en/ui.json" }
  ]
}

.mdoc selecciona Markdoc automáticamente; indicar el formato de forma explícita deja clara la intención. Si un proyecto existente almacena sintaxis de Markdoc en .md, establece format: "markdoc" explícitamente. De lo contrario, la detección por extensión selecciona Markdown convencional. Esa diferencia importa para las etiquetas personalizadas y los atributos de componentes seleccionados.

Selecciona expresamente los campos visibles de la cabecera de metadatos. Mantén sin cambios las fechas, los autores, los ID estables y los metadatos de enrutamiento, salvo que tu política de contenido exija una transformación específica. Declara propiedades de componentes como traducibles solo cuando contengan texto destinado a quienes leen el contenido. Consulta Markdoc para conocer el comportamiento del controlador y Configuración de la CLI para ver los nombres de las opciones de archivo; las opciones de la API de documentos utilizan un esquema diferente.

Utiliza un catálogo de interfaz por idioma. Para otras estructuras de generadores de sitios, consulta Contenido estático.

Renderiza la página de inicio original a través de la ruta de su idioma #

Añade a src/content/en/pages/home.mdoc un título y una descripción en la cabecera de metadatos YAML, seguidos del cuerpo del artículo. En src/content/en/ui.json, añade {"home": "Home"} para la etiqueta de navegación. Instala @markdoc/markdoc y yaml si aún no son dependencias del proyecto.

Esta versión mínima de src/app/[lang]/page.tsx lee la página de inicio de origen y la de destino mediante el mismo mecanismo de carga. Utiliza los parámetros de ruta basados en promesas del App Router actual:

tsx
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";

export const runtime = "nodejs";

export default async function Page({
  params,
}: {
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;
  if (lang !== "en" && lang !== "es") notFound();

  const root = path.join(process.cwd(), "src/content", lang);
  let rawDocument: string;
  let rawUi: string;
  try {
    [rawDocument, rawUi] = await Promise.all([
      readFile(path.join(root, "pages/home.mdoc"), "utf8"),
      readFile(path.join(root, "ui.json"), "utf8"),
    ]);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
    throw error;
  }

  const ast = Markdoc.parse(rawDocument);
  const errors = Markdoc.validate(ast);
  if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
    throw new Error("Invalid Markdoc document");
  }
  const metadata = parseYaml(ast.attributes.frontmatter ?? "");
  const ui = JSON.parse(rawUi);
  if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
    throw new Error("Missing homepage title or navigation label");
  }

  const tree = Markdoc.transform(ast);
  return (
    <main lang={lang}>
      <nav><a href={`/${lang}`}>{ui.home}</a></nav>
      <h1>{metadata.title}</h1>
      {Markdoc.renderers.react(tree, React)}
    </main>
  );
}

Abre primero /en. Este ejemplo utiliza nodos estándar de Markdoc. Si el sitio tiene etiquetas personalizadas, pasa su configuración real tanto a Markdoc.validate como a Markdoc.transform y, después, proporciona a Markdoc.renderers.react los componentes React con los nombres correspondientes. Pasa las variables necesarias de forma explícita. El controlador de traducción conserva las anotaciones; no proporciona el esquema de etiquetas del sitio.

Extiende el mismo cargador con validación a la generación de metadatos y a otras rutas. Para los slugs dinámicos de documentos, resuelve una entrada conocida del inventario antes de leer una ruta. Un cargador basado en el sistema de archivos de Node necesita que los archivos de contenido estén incluidos en el artefacto desplegado; comprueba que se incluyan en la compilación de producción. Un despliegue en un entorno Edge sin acceso al sistema de archivos necesita un lector de almacenamiento diferente.

Coordina la negociación del idioma y la navegación #

Para las rutas sin idioma, utiliza la preferencia explícita de la aplicación o negocia un idioma admitido a partir de Accept-Language. Analiza las ponderaciones de calidad y las etiquetas regionales y, después, redirige a la ruta [lang] correspondiente conservando el resto de la ruta.

No redirijas las rutas que ya contengan un idioma admitido, las solicitudes a la API, los recursos internos de Next.js ni los archivos estáticos. Un criterio de coincidencia demasiado amplio puede crear bucles o redirigir solicitudes de imágenes a rutas de documentos. Aplica las exclusiones admitidas por la API de interceptación de rutas de la versión de Next.js instalada. Los proyectos más antiguos utilizan middleware; las versiones más recientes pueden utilizar la convención que ahora se denomina proxy. Ajusta el comportamiento y las pruebas a la versión instalada, en lugar de copiar un nombre de archivo antiguo como solución universal.

Construye los enlaces internos y a otros idiomas a partir de correspondencias de rutas conocidas. Confirma que cada destino exista antes de ofrecerlo en un selector de idioma. Comprueba también los fragmentos de los encabezados, ya que los encabezados traducidos pueden generar ID diferentes.

Genera solo rutas cuyos documentos estén disponibles #

Para la generación estática, enumera los pares de idioma y slug admitidos a partir del inventario real de contenido. Inclúyelos en el flujo de trabajo de generateStaticParams del proyecto e inspecciona las rutas generadas. Para la carga dinámica, aplica la misma comprobación del inventario al recibir la solicitud y decide cómo gestionar los archivos que falten. No generes todas las rutas de destino a partir de la lista de idiomas dando por hecho que sus traducciones existen.

Traduce los archivos de destino que falten con lingo push --backfill-missing --wait. Cuando termine, confirma que src/content/es/pages/home.mdoc y src/content/es/ui.json existan y, después, abre /es mediante el mismo cargador. Revisa el título, la descripción, el cuerpo y los enlaces traducidos, así como los bloques de código y la estructura de etiquetas personalizadas. Los ejemplos de código y los atributos que controlan el comportamiento deben conservar el significado y los valores del original.

Si necesitas proteger las correcciones locales de los archivos de destino frente a divergencias, envía sin --wait e inspecciona lingo pull --dry-run antes de recuperar los resultados; la escritura directa tras la espera no incluye ese control. Sigue Conserva las traducciones revisadas.

Verifica una página antes de establecer un ciclo de traducción #

Abre directamente una ruta del idioma de destino y, después, accede a ella mediante la navegación del sitio. Confirma que el encabezado, los elementos de la interfaz, los metadatos y el selector de idioma utilicen el idioma previsto. Comprueba un componente personalizado y un ejemplo de código, y sigue un enlace interno y un fragmento de encabezado. Ejecuta la compilación de Next.js que ya utiliza el proyecto y la validación de Markdoc sobre los archivos traducidos.

Mantén juntos los archivos de origen, los archivos de destino aceptados, la configuración y el Lockfile de la CLI. Los cambios posteriores en el origen siguen el flujo de trabajo habitual de lingo push --wait. Una vez que la página funcione, elige la traducción gestionada en GitHub o una receta de ejecución con escritura de resultados que permita su revisión. Mantén la validación del cargador de contenido y la compilación de Next.js en ese ciclo; lingo check no garantiza que los documentos estén completos ni que las etiquetas personalizadas se rendericen correctamente.