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