2026 年 7 月 10 日

• 将 Markdown -> JSONL Converter 官方文档的 JSONL 转换收集量从 1180 条推进到 1230 条
• 多语言翻译流水线比预期延迟更严重，确认可能需要更长时间才能稳定
• 在 private 仓库中测试了多语言文档同步流水线，过程中制定的标准如下

文档结构标准：

• 以韩文文档为基准文档
• 多语言文档放在 docs/<lang>/... 形式的路径下
• 原本直接位于 docs/ 下的子路径视为韩文基准文档，迁移到 docs/ko/... 下
• 语言代码使用标准语言代码，如 ja、zh、pt-BR，而不是 jp、ch 等随意代码
• 根目录的 README.md 保持为根文档
• README 的翻译本也以根目录为基准处理
• 防止 README.md 的修改错误地传播为 docs/ 内文件的修改
• 已存在的 docs/en、docs/ja 等语言文件夹不要出现 docs/ko/en 之类的嵌套
• 压缩文件测试时仅解压 README 与 docs 并进行反映

链接和路径标准：

• README 与 docs 内部链接需根据目标语言进行替换。例如韩文 README 中的 docs/ko/... 链接在英文 README 中改为 docs/en/...
• docs 内部文档之间的相对路径也按目标语言基准进行替换
• 确保图片路径、子目录链接、相对路径在翻译/同步过程中不被破坏
• README 的语言链接应呈现为用户能够感知到跳转或切换到相应语言文档的形式

自动同步标准：

• 当 docs/ko 中新增文件时，在其他语言中生成对应文件
• 当 docs/ko 中删除文件时，在其他语言中也删除对应文件
• 当 docs/ko 中的特定文件被修改时，仅将对应的其他语言文件标记为重新生成目标
• 不会每次都从头翻译全部内容
• 已成功的语言/文件不再重复翻译
• 即使出现失败，也不会删除已成功的产出
• 只移除失败的目标文件，下次运行时仅重新生成该文件
• 对文件数量或简单的版本文件进行比较时，已匹配的语言文件夹直接跳过
• 版本文件使用 v1 或数字等简单形式，而非复杂的 JSON/哈希

翻译处理标准：

• 翻译实际使用 API 进行测试
• 不使用 mock 成功处理
• 根据模型的官方上下文/输出限制确定块大小
• 更重视在实际翻译输出超过 max_tokens 时进行截断，而不是仅依据输入上下文
• 翻译块后立即进行检查
• 检查失败的区域放入队列
• 对队列中的失败区域加深层次、细分后再重新翻译/重新检查
• 避免在合并所有块后仅在最后一次检查的结构

检查标准：

• 确认翻译结果中是否仍残留韩文
• 检查空格是否被去除
• 确认 Markdown 结构是否保持完整
• 检查代码块、链接、图片、标题是否保留
• 对于中文等长度会缩短的语言，不仅仅通过长度比较判断
• 实际阅读产出，确认相对于原文没有异常之处

失败日志标准：

• 区分 HTTP 429、504、RemoteDisconnected、finish_reason=length、空响应等失败原因
• 在日志中记录响应头、响应体、耗时、模型名称、输入大小、令牌使用量等信息
• 防止因单个失败导致整个流水线中断或产出丢失
• 若失败重复出现，首先分析原因

NVIDIA API 使用标准：

• 翻译流水线以 NVIDIA API 为基准进行测试
• gpt-oss-120b 的输入上下文最大可达 128k，但根据 NVIDIA API 策略，输出约限制在 4096 token
• 即使可以输入大量内容，输出限制仍可能导致翻译结果被截断，因此实际块大小以 output 4096 token 限制为准
• 以每分钟 40 次调用为基准尝试，若出现错误则采用等待/重试策略

硬编码标准：

• 使用 docs/<lang>、标记、链接正则、代码块解析等结构规则
• 不随意更改或删除特定单词
• 不随意删除 example.com
• 不采用逐个路径注册文档文件的方式
• 不强行替换语言表达或特定句子/单词

运营标准：

• 同时审查 GitHub Actions 与 Mac self‑hosted runner
• 在 Mac 上运行时也采用完成后自动提交/推送的流程
• 像 GitHub Actions 那样提供进度可视化
• 通过日志能够明确看到哪些语言/文件/块正在处理
• 清晰记录分支名称、run URL、失败原因、当前进度

翻译之外，最近发现了一篇有趣的文档。

• 查看 Pollinations APIDOCS.md

• 即使使用 curl 在没有 API Key 的情况下也能收到文本响应，且似乎支持图像生成

• 觉得可以在不创建 API Key、无需担心计费的情况下轻量实验

• 已基于此尝试开发了一些有趣的东西，后续会再多使用后再公开

• 整理了 Qwen Validation Debugger 的版本分离 JSONL 槽结构

  • docs_chunks 作为代码说明依据，保留 Godot 3 代码与 Godot 4 代码各自的说明/无关说明槽
  • 与其为 Godot 3 专用、Godot 4 专用分别创建 JSONL，不如将两者代码一起放入 3 -> 4 转换依据的 JSONL 中
  • 3 -> 4 转换依据 JSONL 的验证期望值设为 Godot 3 代码 是、Godot 4 代码 否
  • 无关转换 JSONL 的验证期望值设为 Godot 3 与 Godot 4 代码均为 否

• 回顾：docs/retrospectives/2026-07-10.md