Open Interpreter 文档多语言化实战中英双语文档的目录约定、同步校验与 CI 机制【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter本文基于 Open Interpreter 仓库中的文档本地化规范 docs-site/LOCALIZATION.md 展开完整讲解该项目的英文/中文双语文档目录结构、逐文件一一对应的约束模型、本地校验命令pnpm docs:locales:check背后的脚本实现scripts/check-doc-locales.mjs以及 CI 如何强制校验、网站文档如何从这些源文件生成。读完之后你能独立完成一次新增/修改文档且中英同步的完整操作流程并理解每一项校验规则在源码中的具体判定逻辑。一、语言与文件布局英文是规范源中文是唯一全量翻译LOCALIZATION.md 开篇定下了两条核心事实英文English是无语言前缀的规范文档语言canonical locale中文Chinese是目前唯一被完整本地化的文档语言。仓库中的文件布局因此形成了清晰的四元对应关系角色英文规范源中文本地化文档正文页docs/slug.mddocs/zh/slug.md网站导航配置docs.jsondocs.zh.json网站落地页内容docs-site/terminal-index.mdxdocs-site/zh/terminal-index.mdx也就是说语言差异只体现在两处路径里多一层zh/前缀以及导航配置文件多一个.zh后缀。以快速入门为例英文页docs/quickstart.mdfrontmatter 为title: Quickstart、description: Install Open Interpreter, ...中文页docs/zh/quickstart.mdfrontmatter 为title: 快速入门、description: 安装 Open Interpreter...。两者文件名去掉语言目录后必须完全一致这是后文所有校验规则的地基。二、逐页配对约束模型LOCALIZATION.md 定义的硬性规则LOCALIZATION.md 的核心要求可以归纳为四条规则正文文件双向一一对应每一篇英文文档都必须存在同文件名的中文文档反之亦然——不允许只加了英文没翻译或翻译了英文里不存在的页面导航页序一致docs.json与docs.zh.json必须包含相同顺序的页面 slug页序可以翻译分组名但页面集合与排列顺序必须一致提交前必须本地校验文档改动提交前运行pnpm docs:locales:check生成物不是规范源网站随后会根据这些文件生成中文 terminal-doc 路由生成的网站路由永远不是编辑文档的规范位置——所有文档编辑都只发生在上表列出的源文件中。其中第 4 条是容易被忽视的工程细节如果网站构建产物里出现了中文路由你也不要去改那个产物而是要回到docs/zh/与docs.zh.json修改源头。这一点在 website-docs-sync.yml 中得到了印证见第五节。三、pnpm docs:locales:check背后的实现逐项解析校验脚本docs:locales:check只是 package.json 中定义的一个 npm scriptdocs:locales:check: node scripts/check-doc-locales.mjs真正的校验逻辑全部在 scripts/check-doc-locales.mjs 中。该脚本依赖 Node.js仓库要求node 22、pnpm 10.33.0见 package.json 的engines字段下面按执行顺序拆解它检查了哪些内容。3.1 确定校验范围语言列表与正文目录const docsRoot path.join(repoRoot, docs); const localizedDocs [{ locale: zh, directory: path.join(docsRoot, zh) }];从源码结构看当前只有zh一个语言条目与 LOCALIZATION.md中文是目前唯一全量本地化语言的表述严格对应。脚本会列出docs/与docs/zh/下所有.md文件名并排序markdownNames函数为后续的双向差集比较做准备。3.2 导航一致性提取并比对两份 JSON 的页面 slugnavigationPages是一个递归函数导航配置的groups/pages允许任意嵌套子分组也是对象它负责把这种树形结构压平成一维页面列表function navigationPages(value) { if (typeof value string) return [value]; if (!value || typeof value ! object) return []; if (Array.isArray(value)) return value.flatMap(navigationPages); return navigationPages(value.pages ?? value.groups ?? []); }normalizePage则做两件事去掉.md/.mdx扩展名、剥掉语言目录前缀英文剥docs/中文剥docs/zh/得到语言无关的 slugfunction normalizePage(page, locale null) { const localePrefix locale ? docs/${locale}/ : docs/; return page.replace(/\.mdx?$/, ).replace(localePrefix, ); }随后脚本用JSON.stringify(englishPages) ! JSON.stringify(chinesePages)做全序比对——注意这比集合相等更严格两份导航不仅页面集合要一致排列顺序也必须逐位相同任何一次调换顺序都会触发报错docs.zh.json must contain the same ordered page slugs as docs.json。对照实际文件可以看到这种严格对应关系docs.json 中Get Started组的[docs/getting-started, docs/quickstart, ...]在 docs.zh.json 中逐位对应[docs/zh/getting-started, docs/zh/quickstart, ...]分组名可以翻译Get Started→快速开始、Model providers→模型提供商但组内页面 slug 的顺序被锁死。3.3 正文双向差集缺页与幽灵页都要报错for (const name of difference(englishNames, localizedNames)) { errors.push(docs/${locale}/${name} is missing); } for (const name of difference(localizedNames, englishNames)) { errors.push(docs/${locale}/${name} has no matching English document); }这是 LOCALIZATION.mdEvery English document must have a Chinese document with the same filename, and vice versa在代码中的直接落地英文有、中文无 →docs/zh/name is missing中文有、英文无 →docs/zh/name has no matching English document。两个方向的报错信息不同方便定位是漏翻译还是误增文件。3.4 逐文件内容检查frontmatter 与未翻译脚手架检测对docs/zh/下的每一个文件脚本还会读取全文做三项内容级检查title frontmatter文件必须以---\n开头的 YAML frontmatter 中包含非空title:字段hasFrontmatterValue函数用正则^title:\s*\S.$逐行匹配description frontmatter同上description:也必填明显的未翻译英文骨架hasObviousUntranslatedScaffolding先剥离所有代码块 围栏内容不参与判断再检测是否存在以下模式之一——以| Command |、| Purpose |、| Value |、| Meaning |、| Role |、| Behavior |开头的英文表头行形如Good First Step、Pull Requests、Built-In Profiles、Custom Profile、Filesystem Rules、Network Rules、Use Files、Better Than Vague Requests的英文标题行。命中即报docs/zh/name contains untranslated English headings or table labels。这条规则的设计意图很实际它不要求逐句翻译但要求结构性元素标题、表格列名已经本地化从而拦住只复制了英文正文、忘了翻译骨架这类最常见的低质量翻译稿。3.5 落地页存在性检查与结果输出脚本最后还显式确认中文网站落地页docs-site/zh/terminal-index.mdx存在缺失则报错。整个校验流程汇总后有任何一条 error → 打印Localized documentation is out of sync:加逐条错误列表以退出码 1 结束这使 CI 能够直接判红全部通过 → 打印一行确认信息例如Localized documentation is complete: 57 English and 57 Chinese documents.数字以仓库当前实际文档数为准。四、本地运行方式与执行前提在仓库根目录执行pnpm docs:locales:check执行前提与注意事项需要 Node.js ≥ 22 与 pnpm ≥ 10.33.0package.json 中engines声明的最低版本脚本用import.meta.url反推仓库根目录因此必须在仓库根目录或其任何子目录通过 pnpm script 间接执行它读取的是根目录下的docs/、docs.json、docs.zh.json、docs-site/它是只读校验不会修改任何文件只报告差异修复方式永远是回到docs/、docs/zh/、docs.json、docs.zh.json中编辑源文件。五、CI 强制校验与网站同步链路LOCALIZATION.md 提到CI runs the same check在仓库中的落点有两个。5.1 拉取请求门禁public-ci.yml.github/workflows/public-ci.yml 的repository-smokejob 在推送到 main、任何 pull request、手动触发时运行其中一步专门负责本地化文档校验- name: Validate localized documentation parity run: node scripts/check-doc-locales.mjs由于它绕过了 pnpm 直接调用node这一步对 Node 版本没有额外封装要求且任何一条 parity 错误都会让该 job 失败从而阻塞合并。这意味着第四节中所有规则文件配对、导航顺序、frontmatter、未翻译骨架、落地页存在性在 CI 中被完整强制执行本地通过但 CI 挂掉的情况基本不会出现——两者跑的是同一份脚本。5.2 文档变更后的网站同步website-docs-sync.ymlLOCALIZATION.md 中网站根据这些文件生成中文 terminal-doc 路由这句话对应的机制是 .github/workflows/website-docs-sync.ymlon: push: branches: [main] paths: - docs/** - docs.json - docs.zh.json - docs-site/** - scripts/check-doc-locales.mjs - codex-rs/core/config.schema.json当main分支上上述任一路径发生变化时工作流会向独立的网站仓库派发open_interpreter_docs_changed事件并附带本次提交 SHAgh api repos/openinterpreter/website/dispatches \ --method POST \ --field event_typeopen_interpreter_docs_changed \ --field client_payload[sha]$GITHUB_SHA从触发路径列表可以看出两点其一同步只监听规范源docs/**、两份导航 JSON、docs-site/**与校验脚本本身完全符合生成物不是编辑位置的原则其二校验脚本自身也纳入了触发范围——脚本规则一变就需要网站重新生成以保持一致。六、实操流程为文档体系新增一篇中英双语页面结合上述机制一次完整的文档变更应当按以下顺序进行以新增示例页my-page为例先写英文规范页创建docs/my-page.md带title与descriptionfrontmatter写同名的中文页创建docs/zh/my-page.mdfrontmatter 的title/description用中文正文确保标题与表格列名已本地化避免触发未翻译骨架检测同步两份导航在 docs.json 的目标分组中插入docs/my-page并在 docs.zh.json同一分组的同一位置插入docs/zh/my-page——顺序不一致会直接报 ordered slugs 错误如涉网站落地页修改docs-site/terminal-index.mdx时记得同步docs-site/zh/terminal-index.mdx提交前跑校验pnpm docs:locales:check全绿后再提交CI 的public-ci会用同一脚本复核一次。七、小结与扩展边界LOCALIZATION.md 用不到 30 行定义了一套非常紧凑的多语言文档治理模型规范源唯一、翻译逐文件配对、导航同序、生成物只读。而 scripts/check-doc-locales.mjs 把它扩展成了五个可机检维度文件双向差集、导航全序比对、title/description frontmatter、未翻译骨架启发式检测、落地页存在性并通过 public-ci.yml 成为合并门禁、通过 website-docs-sync.yml 成为文档变更流向网站的唯一触发器。关于扩展边界可以基于源码结构推断脚本中localizedDocs数组、导航文件名硬编码为docs.json/docs.zh.json以及落地页检查路径硬编码为docs-site/zh/terminal-index.mdx都是当前写死的——未来若要新增语言需要同时扩展这几处脚本逻辑并在docs/locale/、导航 JSON、docs-site/locale/三处补齐对应源文件。当前仓库内中文仍是唯一被该校验体系覆盖的本地化语言。【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考