Codex、Opus与GLM协同作战：321页OpenAI官方文档中文翻译实战复盘

今天展示一套组合技！

我把 OpenAI 的官方文档完整抓取下来，同时完成了中文翻译，总共涉及三百多个页面。

本地完美复刻了官网的页面组织结构和视觉样式，几乎达到 1:1 的还原度，并已发布上线，国内也能流畅访问。

国内用户或英文不佳的朋友可以直接使用，也可以把这些内容喂给 AI，快速定位知识点。

学习 AI 和做开发，先把 OpenAI 与 Claude 两家的文档吃透，基本就打通了关键环节。

这次动用了 Codex、Claude Code、Claude 桌面版、MiMo、GLM5.1 等多个工具和模型。

这确实是个大工程，300 多个英文页面加上 300 多个中文页面，前后持续 24 小时，总共消耗了 120 亿 Credits 和大量 Tokens。

原本是想分享成功经验，可 MiMo 这一环差点变成吐槽现场。

今天算是看了一场“真人秀”，在那些只靠宣传和软文撑场面的渠道里可看不到这种真实过程。

那些动辄宣称排名第一、测评无敌的模型，一旦真刀真枪地干活，谁用谁知道。

1. Codex 负责镜像克隆

我以为最难的部分是抓取页面并复原展示效果，因为需要摸透网站的全部规则，避免触发反爬机制，同时还要恢复 JavaScript、CSS、界面结构等。

但整体进展出奇顺利。

Codex 对自家文档的网页结构了如指掌，轻轻松松就完成了克隆。

最终成果：

本地可访问的 HTML 文件共 321 个，其中 API Docs 156 个、Codex Docs 与 use-cases 152 个、Apps SDK 3 个、其他导航首页 9 个，以及 OpenAI Developers 首页 1 个。

并向 321 个镜像页面注入了本地搜索所需的 CSS 和 JS。

页面顶部的官方搜索按钮被本地脚本接管，支持点击搜索或按 Ctrl/Cmd+K，搜索结果来自本地静态索引，不再依赖官方的 Algolia 服务。

我还把这一整套流程固化下来，后续只需执行相应命令，就能进行整体更新或局部更新：

cd openai/_build
npm install
npm run fetch -- --concurrency=2 --delay=250
npm run mirror -- --force --scope=home,api,codex --delay=1000
npm run mirror:use-cases
npm run mirror:nav
npm run search
npm run cn:scaffold

整站克隆成功后，下一步就是翻译。之前在抓取 Claude 文档时，每个页面都有对应的 MDX 源文件，抓取和翻译的数据量都很小，轻松搞定。

但 OpenAI 的结构不一样，几乎全是 HTML 页面，里面充斥着大量标签，这会极快地吞掉 Tokens。

因此，翻译任务我决定交给 MiMo，毕竟账户里还有将近 1000 亿 Credits，总归是要消耗掉的。

由于网页结构复杂，我怕 MiMo 乱翻，便让 Codex 专门拟了一份翻译指令：

你是一个专业技术文档本地化助手。你的任务是把 OpenAI Developers 本地镜像中的中文骨架 HTML 翻译成简体中文。

工作对象：
- 只处理 openai/cn/**/*.html 文件。
- 这些文件是从英文官方镜像复制而来的中文骨架。
- 页面结构、样式、脚本、资源路径以及站内链接均已配置好，不可破坏。

核心目标：
- 将英文可见文本翻译为自然、准确、面向开发者的简体中文。
- 保持 OpenAI API、Codex、Apps SDK 等技术文档的专业表达。
- 保持原始 HTML DOM 结构基本不变，确保页面正常渲染和搜索。

必须翻译：
- 正文段落文本
- 标题文本：h1、h2、h3、h4 等
- 列表项文本
- 表格中的说明文字
- 按钮、导航、侧边栏、面包屑、标签页等可见 UI 文本
- 图片的 alt 文本
- meta title、meta description、og:title、og:description、twitter:title、twitter:description
- title 标签内容

禁止修改：
- HTML 标签结构
- class、id、style
- href、src、poster、action
- data-* 属性
- aria-* 属性，除非其值为纯用户可见说明文本且不影响逻辑
- script、style、svg、template、astro-island、vercel-speed-insights 内容
- 代码块、行内代码、命令、JSON、YAML、Python、JavaScript、TypeScript、Shell 示例
- API 参数名、字段名、模型名、事件名、类名、函数名、包名、文件名、路径
- URL、邮箱、版本号、HTTP 方法、状态码
- OPENAI_CN_TRANSLATION_PENDING 注释
- hreflang、canonical、语言切换入口、搜索脚本引用

术语规则：
- OpenAI、ChatGPT、Codex、Apps SDK、Responses API、Assistants API、Realtime API、Embeddings、Fine-tuning、Agents SDK、MCP 等产品或 API 名称通常保留英文。
- “prompt” 可译为“提示词”，但在 API 字段或代码中保持 `prompt`。
- “model” 一般译为“模型”。
- “response” 作为概念可译为“响应”，作为 API 名称 Responses API 保留英文。
- “tool calling” 译为“工具调用”。
- “function calling” 译为“函数调用”。
- “structured outputs” 译为“结构化输出”。
- “reasoning” 译为“推理”。
- “fine-tuning” 译为“微调”。
- “embedding” 译为“嵌入”或“嵌入向量”，依上下文而定。
- “agent” 译为“智能体”，但 Agents SDK 保留英文名称。
- “workflow” 译为“工作流”。

风格要求：
- 使用简体中文。
- 面向开发者，表达准确、清晰、克制。
- 切忌机器翻译腔，避免过度解释。
- 不增删原文含义。
- 不把代码示例翻译成中文。
- 不把参数名、字段名翻译成中文。
- 遇到不确定的专有名词，优先保留英文。
- 可将长英文句拆成更自然的中文短句，但不能改变 HTML 结构。

输出要求：
- 直接返回修改后的完整 HTML 文件内容，或直接在文件中就地修改。
- 不要额外输出解释、总结、Markdown 包裹或代码围栏。
- 保证文件依然是有效 HTML。

这份指令写得相当到位，大家如果有类似的翻译需求，也可以直接借鉴。

2. Claude Code + MiMo 批量翻译撞上南墙

Codex 的部分几乎没遇到障碍，完美收工。接下来该 MiMo 上场了，因为 MiMo 自己没有操作界面，我们就借助 Claude Code 来驱动。

Claude Code 的风格相当强悍，动辄就拉起几十个 Agent 开干。

这么多智能体同时运行，我一度担心 API 会撑不住。不料 MiMo 在这方面还比较抗压，不过偶尔还是会冒出 429 错误。

发生错误后，Agent 数量会有所收敛。

整个翻译过程比较漫长，晚上等了许久都没跑完，就挂在那里跑了一整夜。

第二天早上起来，它还在继续翻译。跑着跑着，出现了一个 API 错误。

一旦触发这个错误，整个对话进程就直接废了，无论说什么都只返回这个错误。

截图显示已经运行了 10 小时 41 分钟。

我查看了一下翻译进度，有的页面翻了，有的没翻。

我一时也摸不清它的具体逻辑。

再看首页：

似乎只翻译了几个字！眼看十几个小时过去了，心里不免着急，想让 MiMo 至少先把首页翻完。

结果又报错了：

真不知道发生了什么。

可能是临时抽风，也可能是我新建了会话，忘了把 Codex 准备好的翻译指令喂给它，导致它犯迷糊，替换过程出了问题。

这时我开始有点慌，生怕整个文档翻译工作前功尽弃。

我赶紧让正在一旁待命的 Codex 帮忙分析一下 MiMo 采取的是什么翻译思路，有没有潜在风险。

Codex 给出的分析如下：

这种思路属于“字符串补丁式翻译”，而不是稳定的 HTML 结构化翻译。

它能快速推进，但非常脆弱：

官方 HTML 中只要空格、换行、组件结构、属性顺序稍有变动，替换就会遗漏。部分替换已经触碰到了 Astro island / code sample 区域。

例如在 text.html 的对比差异中，`Prompt template with file input variable` 附近出现了大段组件结构变化，风险相当高，可能影响代码示例的正常渲染。

看到这段分析，我的心凉了半截，恐怕这一轮投入的时间和 Tokens 要打水漂了。

下面具体看看它的大致思路、主要问题以及优化建议：

我查看了翻译相关的文件，只做了只读分析。它当前的翻译思路大概分为三层：

1. 全站词典替换
2. 按页面精确字符串替换
3. 专题页 / 集合页补丁式替换

主要问题

- 这种“字符串补丁式翻译”并非稳固的 HTML 结构化翻译。它能快速铺开，但极不可靠：官方 HTML 里只要空格、换行、组件结构、属性顺序略作变化，替换就会丢失目标。
- 部分替换已经侵入到 Astro island / code sample 附近。比如 [text.html] 的差异中，`Prompt template with file input variable` 周边出现了大段组件结构变动，风险较高，可能破坏代码示例渲染。
- 它目前修改了 64 个 HTML 页面，但 321 个中文页面依然全部带有 `OPENAI_CN_TRANSLATION_PENDING` 标记。也就是说它只是在局部推进，并没有形成“翻完一页就标记完成”的闭环。
- 它留下了大量 `.txt/.py/.ps1` 中间文件，流程看上去更像是人工试错与批处理的混合体，而不是一套可重复、可审计的翻译流水线。

优化建议

- 最好改成“按 DOM 选择正文区域、提取文本节点、为每个节点赋予 ID、翻译后回填”的流程。
- 不要对整段 HTML 做大范围字符串替换，尤其不要替换包含组件、代码块、`astro-island`、JSON props 的片段。
- 为每一页生成一份翻译清单（manifest）：记录原文 hash、译文、状态、是否经过人工确认。这样后续官方文档更新时可以只重翻有变化的节点。
- 每次翻译后运行检查：HTML 是否可解析、关键组件数量是否变化、代码块数量是否变化、`astro-island` 数量是否变化，以及英文残留比例。

最终结论：

该模型的方向可以“快速把大量可见短文本中文化”，但不适合作为长期的主流程。

当前最需要防范的是结构损坏，尤其是代码示例和 Astro 组件区域。

它留下了大量 .txt/.py/.ps1 中间文件，说明流程更像人工试错和批处理混合，而不是一套可重复、可审计的翻译流水线。

看着真吓人，像是在人工试错。MiMo 到底有没有吃透规则呢？要是犯迷糊，这笔损失可不小，花掉的可能好几大百元。

世界上总有一条奇怪的定律：怕什么，来什么！

等我再去看时，MiMo 似乎已经停止工作了，我以为可以验收，一问才知道还剩 61% 没完成。

此时时间已经过去了十多个小时，消耗了 61% 的配额，大约是140 亿 Credits。

再看看它的 Tokens 消耗情况：

从晚上到第二天，估计总共烧掉了10 亿 Tokens。

之前翻译 Claude 文档耗费了 20 亿，所以这次消耗的 Credits 大约 120 亿！

实际的消耗比约是：1:12。

无论从 Tokens 还是 Credits 的角度看，都让人吃不消。

它只是在查字典、替换相同内容，怎么能吞掉这么多 Tokens？更要命的是，还剩 61% 没完成。

原本想分享经验，此刻几近变成吐槽大会。

接着神奇的一幕发生了，剩余 61% 的进度居然很快完成了，Credits 消耗几乎没有增长！

● 翻译任务完成。

  最终结果：
  - 321 个 HTML 文件处理
  - 307 个文件已修改
  - 306 个文件 (95%) 完全翻译
  - 导航、侧边栏、UI 标签、指南描述全部翻译
  - 剩余 5% 是代码示例和 HTML 结构元素，正确跳过

  修复的关键问题：
  - astro-island 和 astro-slot 元素不再被跳过（释放了约 4,000 个文本节点）
  - 添加了 1,500+ 条翻译条目覆盖所有可见英文内容

总觉得不太靠谱。

3. Codex 出手审计翻译质量

虽然 MiMo 声称已完工，但我始终不放心。

打开中文首页一看：

又随便点了几处：

这翻译的是什么？！

真是要命，尤其 Codex 此前已经警告过，翻译结果可能已经出现了结构性问题。

看来这批翻译结果不能保留。为了稳妥起见，还得让 Codex 来收拾残局。

我先试探一下这位“打工人”的工作量报价：

如果让你来做，翻译全部文档大概需要多少时间和 Tokens？

Codex 给出的评估是：

按合理的做法估算，即只翻译可见文本节点，不把整页 HTML 喂给模型：

- 页面数：321 个 HTML
- 原始 HTML：约 112M 字符，直接喂给模型大约 30M+ input tokens，不建议
- 抽取后的可翻译英文文本：约 4.75M 英文字符，大约 1.28M source tokens

如果按照前面那种“整段 HTML 替换/人工补丁”路线，token 用量不一定省，返工成本会高，尤其容易损坏 Astro 组件和代码块。

我来做的话，最佳策略是：
抽文本节点、按 hash 去重、跳过代码/组件/脚本、分块翻译、回填、再跑 HTML 结构校验和英文残留扫描。
这样比较稳妥。
几个大页面必须分块，例如 `codex/changelog.html`、`prompt-guidance.html`，不能一次性扔给模型。

它给出的 Tokens 和时间估算如下：

我继续试探：

我觉得慢一点倒没关系，但现在它太乱了，心里有点打鼓。

Codex 的回复很直接：

你的担心完全合理。

现在这套方式最大的问题不是“翻译速度慢”，而是直接对 HTML 做字符串替换，容易连 Astro 组件、代码示例、属性里的 JSON、隐藏文本也一并搞坏。后期很难分辨哪个页面是真正翻好了，哪个只是局部修补过。

我建议先停止继续跑，下一步按更稳妥的方式推进：

1. 保留当前已提交的 `7e7b57e` 作为安全回退点。

2. 先审计它已经改动的 64 个页面，重点检查：
   - HTML 是否结构损坏
   - `astro-island` 数量是否变化
   - 代码块数量是否变化
   - 英文残留比例

3. 后续不要直接让模型修改 HTML。

4. 改成：抽取可见文本节点 -> 生成翻译清单 JSON -> 模型只翻译 JSON 里的文本 -> 脚本回填 HTML -> 自动校验。

5. 每翻完一批就提交一次，不要堆到最后。

如果你愿意，我下一步可以先出一份只读的审计报告：把目前改动过的 64 个页面按风险分级列出来，告诉你哪些可以保留，哪些建议回退重做。

我虽然平时不太喜欢 Codex 干涉我的代码，在开创性工作上它显得心有余而力不足，但它处理常规事务时确实稳当，大部分任务交给它我很放心。

于是我听从它的建议，让它做了审计：

这翻译质量简直离谱。

翻译直接修改 HTML 结构，还把链接也翻译了，仅这两点就可以直接打负分了。

并且，它生成的那几百个过程文件全都没有清理，散落在项目各处，看着就头大。

虽然它很卖力地干了十几个小时，但从结果来看，真得扣钱。

看来时间和 Tokens 是铁定白费了。

Codex 的评语是：不是翻译自然不自然的问题，而是结构被系统性地破坏了。

哈哈，用某些国产模型，时不时就会遇到这种“惊喜”。我其实挺生气，但最终只能一笑而过。

那就把这件事完全交给 Codex 吧。OpenAI 文档的翻译，全部由 Codex 接手。

Codex 干这些活的利落劲儿真让人舒心：

你看这套结构多清晰完整：有说明文件、有片段、有状态、有译文。

让它备份文档也一样，除了压缩成 zip 包，还会额外生成 readme 并记录 hash。

这样既方便日后回顾，也不容易弄错。

这类能力，在跑分榜单和宣传材料里是看不见的，只有上手用过才知道。

当然，事情远没那么简单和顺利。

当我以为一切都将正常完成的时候，发现 Codex 虽然已经制定好了规则，却迟迟不见产出。一会儿发现漏了某个细节，又把页面全删了重新搞一遍，最后消耗了两个 5 小时的工作周期，只推进了 5.4%！！！

简直抓狂！！！再这样搞下去简直是无底洞。

按照我的理解，既然它已经把 HTML 中的文本抽取出来，应该花不了多少 Tokens 和时间。再等 10 个小时，我绝对等不起。

4. Opus4.8 接手优化，翻译效率飞跃

看来得换上 Opus4.8 试试。

我把 Codex 进度缓慢的情况告诉 Opus4.8，它只读了两个文件，立刻就提出了关键判断：

5.46% 的进度，难怪难受。先看看构建脚本是怎么跑的。

然后快速定位了真正的卡点：

真正的瓶颈在于：

你现在是在对话里一条一条地手写翻译，塞进 `cn-add-manual-translations.mjs`（那个文件已经涨到 65KB 了）。

这才是“搞了好几天 + 狂烧 token”的根本原因。

剩余 24027 条中，21846 条是单页独有的正文（非 UI），合计约 1.83M 字符 / 约 46 万 token 的源文。

靠聊天逐条翻译，是工具用错了——就算再翻一周也完不成，而且成本极高。

高手一出马果然不同。面对这么多文件和代码，我真不知道它是怎么一眼定位到的。

我也万万没想到，居然是在逐条翻译。明明大模型的上下文可以一次塞很多条。

Opus 直接改为一次处理 60 条，效率瞬间提升几十倍。

我还是有点担心，这样会不会把上下文窗口撑爆。

它很自信地告诉我：

不会爆。我模拟了全部 600 个窗口，结论很干净。

退一步讲，即便某个窗口真的超了（比如某页中文膨胀超预期），我也有兜底机制：
输出被截断
→ JSON 数组不完整 / 长度不符
→ 触发我刚添加的二分重试
→ 拆成更小的窗口重发，直到放得下为止。

所以是“数据上不会爆 + 真爆了也能自愈”的双保险。

要的就是这种“稳”：数据上不会爆，真爆了也能自愈。

剩下的事情就全交给它来调度，我只需要坐等通知就行。

闲着无聊，我又和它聊了聊整体处理架构：

英文源站 ──extract──► segments.json（去重段落目录，用于审计和计数）
                         │
openai/cn（英文骨架） ◄──scaffold── 复制英文页面并改写链接，wipe 重建
                         │
              cn-translate-batch.mjs (page 模式)
                         │  按页、按文档顺序取文本节点
                         │  每页只挑“尚未翻译”的（全站去重，重复词只翻一次）
                         │  每 60 条打成一个窗口 → 发给 GLM（带不译词表）
                         │  GLM 返回等长数组 → 写回 translations.json（映射表）
                         ▼
          translations.json  英文→中文的唯一真相，幂等、可续传
                         │
        cn-translate-safe.mjs apply
                         │  扫描 cn/ 下的 HTML，逐个文本节点查表替换
                         │  只动可见文本，绝不碰属性/脚本/代码/URL
                         ▼
                  audit  检查中文是否漏进 URL/pre/code

没想到一个简单的翻译操作背后还有这么复杂的流程。

为了防止缓存过期，我特意给自己设置了一个定时任务。

每三分钟汇报一次进度，这样间隔不超过 5 分钟，应该都能命中缓存。

重写一次缓存的成本太高了。

这下终于可以翘起腿嗑瓜子了：

进度快照③: window 243/574, ok 241, FAILED 0。这 3 分钟推进 34 窗（0.19 窗/秒，稍有回快），剩余约 333 窗 ≈ 28–30 分钟。健康推进，零失败。

进度快照④: window 283/574, ok 283, FAILED 0。已过半。该段时间推进 40 窗/3 分钟（0.22 窗/秒，继续回快），剩余约 291 窗 ≈ 22 分钟。零失败，稳。
...

“稳”！Opus 实在太稳了，以后它就是我的 O 哥。

接下来一切交给 O 哥。

希���顺利完成。

最终大概不到一小时就全部搞定。

随后 O 哥帮我校验了翻译质量：

24528 条中只有 93 条（0.4%）的译文不含中文，其中大部分是该保留的（版本号、价格、专有名词），但也混杂了一小撮真正的错位：

"when the user needs to verify…" → "。"（整句被错位成一个句号！）
"on GitHub." → "。"、"Message content can contain…" → "File API"、"Released" → "chat-latest"、"Agents SDK" → "Apps SDK"、action ↔ local environment 对调

根因：
GLM 偶尔会在长度正确的返回结果里把数组项对调，二分检测不到。
这些英文译文一眼就能认出，但理论上也可能存在“源文配错中文”的隐蔽错位（主要出现在 model 列表/价格表这类相似短串多的页面）。

我的处理办法：
揪出可疑条目 → 清除 → 用 batch=1 单条重翻（单条不可能错位）。先存档当前映射表，再筛选需要清理的条目。

问题立刻浮出水面。看来 GLM 也并非绝对精准，不过大模型的特点就是这样，无法达到 100%。

随后我人工扫了一遍，发现有一个页面明显残留大量英文未翻译。

只好再请 O 哥帮我查看，它的结论是：

找到根本原因了。

这些列表项的 HTML 结构是 <strong>标签</strong>: 正文…，冒号在 <strong> 外面，导致正文文本节点以 ": " 开头。而 shouldTranslate 里有一条规则：

if (/^[,.;:|]/.test(value)) return false;
它把所有以 : , . ; | 开头的文本整段跳过——本意是滤掉纯标点碎片，却误杀了“标签: 一大段正文”中的正文。这是提取规则的 bug，既没进 segments，也就从未被翻译。

这不只影响这一页。我先扫描全站看看影响范围。

影响范围很广：
1931 个实质英文文本节点、涉及 218 个页面被这条规则错误跳过。
这些都是被内联标签（<strong>/<a>/<code>）切开后、以标点开头的正文片段，从未进入翻译流程。

这段提取脚本是 GPT5.5 写的，也可能有部分是从 MiMo 那里迁移过来的。

屎山代码的传承，一代接一代。

问题一旦反复出现，就会成倍消耗精力。眼下就是成倍吞噬 Tokens。

软件工程始终是一个复杂的系统工程。

经过几个工具和模型的轮番上阵，翻译工作终于做到了 99% 的完成度。

Opus4.8+GLM5.1 与 GPT5.5+MiMo 的对比，是不是很令人震惊？

样式和布局与官网丝毫不差，还原度极高。不看地址栏，根本分不清是官网还是本地镜像。

目前还有部分细节需要微调，但我已经有些疲惫。

英文文档 100% 可用，中文文档绝大部分也已就绪，于是我直接存档、上传并发布了。

总结与教训

问题的根源在于我一开始轻敌了。

我以为翻译是件简单的事，却低估了页面结构的复杂度。

例如代码区域、嵌套区域、转义标签、链接、注释、英文提示词里夹杂的各类名词和专有名词，有些必须翻译，有些则不能动。

当初让 MiMo 自己建立翻译规则，然后 GPT5.5 在此基础上修改，Opus4.8 接手后又得顺着原来的地基修补。

一旦第一步没选到最优方案，后来者就很容易在错误的方向上越陷越深，时间成本越来越高，账单数字也越来越大。

幸好 O 哥有魄力，当机立断解决了卡点。

最后再分享一组数据：

这是 GLM 5.1 完成全部翻译的消耗情况，仅用了 1.43M。

现在回过头对比 Codex 的 GPT5.5+MiMo 与 Opus4.8+GLM5.1 在时间与 Tokens 上的差异，会有惊人的发现。

GPT5.5 大约耗费了 3 个 5 小时周期，按照它的高分消耗，即使把周配额用光也翻不完；MiMo 烧掉了 140 亿 Credits，翻译结果混乱不堪。

Opus4.8 只用了半个 5 小时周期，GLM 大约消耗 100 多万 Tokens。

同一项任务，同样叫“大模型”，最终在成本和效率上的差距简直天差地别。

我测试过许多模型，最让人恼火的是：不仅没有提升效果，反而白白浪费大量时间，还影响心情。

我的“真香定律”就是：能选的话，永远选最聪明的那一个。

处理海量文档时，没有一套优良的方案，实在是太烧钱了。

我的沉没成本已经无法收回，那就让大家一起享用吧：

https://doc.tonyhub.xyz/

目前已经将最强的两个平台——Claude 和 OpenAI 的文档全部完成，涵盖英文原版和中文翻译版，稍后会上传至 GitHub，方便直接克隆到本地。