Localiza Markdoc con Next.js

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

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

Usa 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 sin cambios cuando sean identificadores de contenido. Traducir un encabezado no requiere cambiar el nombre de home.mdoc. Si decides localizar los slugs, mantén un mapeo explícito para la navegación y los enlaces a otros idiomas; traducir el cuerpo no crea ese mapeo.

Verifica que el idioma de la ruta y el slug del documento pertenezcan a conjuntos conocidos antes de construir una ruta del sistema de archivos. Define cómo manejar las traducciones faltantes: devolver una respuesta de recurso no encontrado o usar explícitamente el idioma de origen como alternativa. El ejemplo de página de inicio que aparece más abajo usa un nombre de documento fijo y devuelve una respuesta de recurso no encontrado para los idiomas no compatibles o los archivos faltantes.

Selecciona el procesador 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 los ID generados de la organización y del motor de localización en .lingo/config.json y luego 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, configura format: "markdoc" explícitamente. De lo contrario, la detección por extensión selecciona Markdown estándar. Esa diferencia importa para las etiquetas personalizadas y los atributos de componentes seleccionados.

Elige con cuidado los campos visibles de los metadatos iniciales. 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 las propiedades de los componentes como traducibles solo cuando contengan texto dirigido a quienes leen. Consulta Markdoc para conocer el comportamiento del procesador y Configuración de la CLI para ver los nombres de las opciones de archivo; las opciones de la API de documentos usan un esquema diferente.

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

Renderiza la página de inicio de origen desde la ruta de su idioma #

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

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

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 /en primero. Este ejemplo usa nodos estándar de Markdoc. Para un sitio con etiquetas personalizadas, pasa la configuración real del sitio tanto a Markdoc.validate como a Markdoc.transform y luego proporciona a Markdoc.renderers.react los componentes de React con los nombres correspondientes. Pasa las variables necesarias de forma explícita. El procesador de traducción conserva las anotaciones; no proporciona el esquema de etiquetas del sitio.

Extiende el mismo cargador validado 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 del sistema de archivos de Node requiere que los archivos de contenido estén incluidos en el artefacto desplegado; verifica que se incluyan en la compilación de producción. Un despliegue en Edge sin acceso al sistema de archivos necesita un lector de almacenamiento diferente.

Asegura la coherencia entre la negociación de idioma y la navegación #

Para las rutas sin idioma, usa la preferencia explícita de la aplicación o negocia un idioma compatible a partir de Accept-Language. Analiza los pesos de calidad y las etiquetas regionales y luego redirige a la ruta [lang] correspondiente, conservando el resto de la ruta.

No redirijas las rutas que ya tengan un idioma compatible, las solicitudes de API, los recursos internos de Next.js ni los archivos estáticos. Un patrón de coincidencia demasiado amplio puede crear bucles o redirigir solicitudes de imágenes a rutas de documentos. Aplica las exclusiones que admite la API de interceptación de rutas de tu versión instalada de Next.js. Los proyectos anteriores usan middleware; las versiones más recientes pueden usar esa convención con su nuevo nombre, proxy. Mantén el comportamiento y las pruebas alineados con la versión instalada, en lugar de copiar un nombre de archivo antiguo como si fuera una receta universal.

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

Genera solo las rutas cuyos documentos estén disponibles #

Para la generación estática, enumera los pares de idioma y slug compatibles a partir del inventario real de contenido. Inclúyelos en el flujo de generateStaticParams del proyecto y revisa las rutas generadas. Para la carga dinámica, aplica la misma comprobación del inventario al recibir cada solicitud y define cómo manejar los archivos faltantes. No generes todas las rutas de destino a partir de la lista de idiomas suponiendo que sus traducciones existen.

Traduce los archivos de destino faltantes con lingo push --backfill-missing --wait. Al terminar, confirma que src/content/es/pages/home.mdoc y src/content/es/ui.json existan y luego 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 delimitados 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.

Cuando las correcciones locales de los archivos de destino necesiten protección contra divergencias, envía la solicitud sin --wait y revisa 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 traducir de forma recurrente #

Abre directamente una ruta del idioma de destino y luego navega hasta ella desde el sitio. Confirma que el encabezado, los elementos de la interfaz, los metadatos y el selector de idioma usen el idioma previsto. Revisa 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 existente en 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 usan el flujo habitual de lingo push --wait. Una vez que la página funcione, elige la traducción administrada en GitHub o una receta de ejecución que permita revisar la escritura de los resultados. 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.