在 Next.js 中本地化 Markdoc

在 Next.js App Router 应用中,为不同语言区域的 Markdoc 文档配置路由、加载、翻译和渲染,并搭配独立的 UI 文案目录。

译文需要与页面上的其他内容保持一致。在 Next.js 网站中,路由的语言区域既可以决定加载哪个 Markdoc 文档,也可以决定导航使用哪个独立的 UI 文案目录。本指南将这些文件接入 App Router 页面,再通过 CLI 完成翻译。

使用已集成 Markdoc 的现有 Next.js App Router 项目。本示例在服务器端读取本地文件,不依赖 React 本地化适配器。

选择按语言区域组织的文件布局 #

示例项目可以按语言区域将文档和 UI 文案目录放在一起:

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

如果 slug 用作内容标识符,请保持它不变。翻译标题并不需要重命名 home.mdoc。如果确实要本地化 slug,请为导航和其他语言版本的链接维护明确的映射;翻译正文不会自动生成这些映射。

构建文件系统路径前,请确保路由的语言区域和文档 slug 都属于已知集合。同时确定翻译缺失时的处理策略:返回“未找到”响应,或明确回退到源语言。下面的首页示例使用固定的文档名称,并在语言区域不受支持或文件缺失时返回“未找到”响应。

选择 Markdoc 处理器和可见元数据 #

在项目根目录安装并关联 CLI:

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

将生成的组织 ID 和本地化引擎 ID 保留在 .lingo/config.json 中,然后配置完整的源文件选择范围:

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 会自动选择 Markdoc;显式指定格式能让配置意图更清晰。如果现有项目将 Markdoc 语法存储在 .md 中,请显式设置 format: "markdoc"。否则,扩展名检测会选择普通 Markdown。这一区别会影响自定义标签和选定的组件属性。

请明确选择需要翻译的可见 frontmatter 字段。除非内容策略要求进行特定转换,否则请保持日期、作者、稳定 ID 和路由元数据不变。只有包含面向读者的文本时,才应将组件属性声明为可翻译属性。处理器行为请参阅 Markdoc,文件选项名称请参阅 CLI 配置;文档 API 选项采用不同的结构定义。

每个语言区域使用一个 UI 文案目录。其他站点生成器的文件布局请参阅静态内容。

通过源语言的语言区域路由渲染首页 #

在 src/content/en/pages/home.mdoc 的 YAML frontmatter 中添加标题和描述,后面接文章正文。在 src/content/en/ui.json 中添加 {"home": "Home"} 作为导航标签。如果 @markdoc/markdoc 和 yaml 尚未列入项目依赖,请先安装。

这个最简 src/app/[lang]/page.tsx 使用同一加载路径读取源语言和目标语言的首页,并采用当前 App Router 基于 Promise 的路由参数:

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

先打开 /en。本示例使用标准 Markdoc 节点。如果网站使用自定义标签,请将网站的实际配置同时传给 Markdoc.validate 和 Markdoc.transform,再将具名 React 组件传给 Markdoc.renderers.react。所需变量也必须显式传入。翻译处理器会保留注解,但不会提供网站的标签结构定义。

将同一个带校验的加载器扩展用于元数据生成和其他路由。对于动态文档 slug,请先解析出已知内容清单中的条目,再读取相应路径。使用 Node 文件系统加载器时,部署产物必须包含内容文件;请确认生产构建已包含这些文件。无法访问文件系统的 Edge 部署则需要使用其他存储读取器。

让语言区域协商与导航保持一致 #

对于未包含语言区域的路由,请使用应用中明确设置的偏好,或根据 Accept-Language 协商出受支持的语言区域。解析质量权重和地区标签后,重定向到对应的 [lang] 路由,并保留路径的其余部分。

不要重定向已包含受支持语言区域的路由、API 请求、Next.js 内部资源或静态文件。匹配范围过宽可能导致重定向循环,或将图片请求重定向到文档路由。请使用当前安装的 Next.js 路由拦截 API 所支持的排除规则。较早的项目使用中间件;较新版本可能采用更名后的 proxy 约定。行为和测试应与已安装的版本保持一致,不要将旧文件名当作通用方案照搬。

根据已知路由映射构建内部链接和其他语言版本的链接。在语言切换器中提供目标链接前,请确认每个目标都存在。也要检查标题锚点,因为翻译后的标题可能生成不同的 ID。

仅为已有文档生成路由 #

进行静态生成时,请从实际内容清单中枚举受支持的语言区域与 slug 组合,将这些组合纳入项目的 generateStaticParams 流程,并检查生成的路由。使用动态加载时,请在请求阶段执行同样的清单检查,并明确处理文件缺失的情况。不要仅根据语言区域列表生成所有目标路由,就假定对应的译文一定存在。

使用 lingo push --backfill-missing --wait 翻译尚未生成的目标文件。完成后,确认 src/content/es/pages/home.mdoc 和 src/content/es/ui.json 已存在,再通过同一个加载器打开 /es。检查译文中的标题、描述、正文、链接、代码围栏和自定义标签结构。代码示例和影响行为的属性应保留源文件中的含义和值。

如果对目标文件的本地修正需要差异保护,请在提交时不使用 --wait,并在获取结果前检查 lingo pull --dry-run;直接等待并写回的方式没有这一检查关口。请遵循保留已审核的翻译中的说明。

让翻译定期运行前,先验证页面 #

先直接打开目标语言区域的路由,再通过网站导航进入该路由。确认标题、界面元素、元数据和语言切换都使用预期的语言区域。检查一个自定义组件和一个代码示例,并访问一个内部链接和一个标题锚点链接。针对翻译后的文件,运行项目现有的 Next.js 构建和 Markdoc 校验。

将源文件、已接受的目标文件、配置和 CLI Lockfile 保存在一起。后续源文件变更沿用常规的 lingo push --wait 工作流。页面正常运行后,可以选择托管式 GitHub 翻译,或采用支持审核写回内容的 运行器方案。请在这一流程中保留内容加载器的校验和 Next.js 构建;lingo check 无法确保文档完整,也无法确保自定义标签正确渲染。