背景
很长一段时间内，DragonOS社区都只有中文文档。原因是我觉得主要参与者是国内的同学，希望降低大家参与DragonOS的门槛。随着项目不断发展，不断有朋友跟我说：如果DragonOS可以有英文文档，更国际化一些，能让外国友人也了解这个项目，那就更好了。
为什么之前一直没干这件事？
但是在很长一段时间内，我没有把这个文档国际化相关的工作推进实施。这主要是因为，投入大，费时间。一想到要维护多个语言版本的文档，还要保持内容同步，真的是太费劲了。
那为啥不让同学们用英文写文档？除非你的英语真的很nb，否则我打赌，肯定得花更多时间琢磨如何措辞之类的问题。然后写出来之后，国内的开发者还得费老劲去读。（google traslate的那机器味文字，你受的了吗？哈哈哈哈哈哈哈哈）
现在是怎么办的？
现在是这样的，我写了个doc_translator来帮助自动翻译文档。
整个文档翻译的自动化流程是这样的:
我在github workflow里面配置了，只要docs目录下面发生更改，就会触发文档翻译的工作流。文档翻译工作流会调用AI，把文档翻译了，并且输出到docs/locales目录下面，接着创建一个新的文档翻译pr。
效果如何？
请看IMG（恩这里没有VCR）：
详情请见
https://docs.dragonos.org.cn/locales/en/index.html
doc translator的原理
对于一篇文档，翻译的流程如上图所示。
这里有几个关键点，让我逐一讲解一下：
文档翻译缓存：
由于每次文档变动的时候，可能只有几个文件变了，其他的没变，为了只翻译那些有变动的文档，翻译器会在docs/.translation_cache.json 内，存储翻译缓存信息。这是基于文件哈希的缓存机制，其中的hash是原始文件的hash。
一旦目标语言的文档在cache里面对应的原始文件的hash与实际值不一致（就是说，源文档更新了），或者cache里面没有，那么就认为该文件需要被翻译为目标语言，于是就会启动翻译。
引用标签管理
文档内部总是有些引用标签（便于跳转的），但是在同一个文档项目里面，引用标签的定义是不能重复的，因此，为了避免冲突，使用了下面这个方式来为翻译后的文档生成引用标签：
格式保护机制
翻译过程中需要保护特殊格式不被破坏：
通过占位符机制保护：
- 多行代码块 (“`…“`)
- 内联代码 (…)
- 特殊排除区域
举个例子，代码块在发送给AI模型之前，被替换为了__CODE_BLOCK_xxxxxxx 这样一个标志符，接着在AI翻译结束之后，再把他替换回原文，就避免了大模型错误修改代码块的问题。
自动清理机制
翻译器还能自动清理孤立的翻译文件，当源文件被删除时，对应的翻译文件也会被自动清理。
用的什么模型？
经过测试，最终决定用的是硅基流动上面的qwen3-8b模型。原因是：
- 很听话：能够智能识别我上面说的“标签替换”，把替换后的标签能原封不动的返回回来，不至于修改了或者丢了。
- 免费！是的，这个不用花钱就很棒。
小结
这样一来，DragonOS的文档国际化问题就完美解决了。开发者可以继续用熟悉的中文写文档，而国际友人也能通过英文版本了解项目。真正做到了鱼和熊掌兼得！哈哈哈哈
想了解更多技术细节？欢迎查看我们的GitHub仓库，doc_translator的完整代码都在tools/doc_translator.py中。
发表回复