「2023.004|CN」最佳实践系列：技术文档多语言支持

发表于 阅读次数： 本文字数： 3.9k 阅读时长 ≈ 14 分钟

技术文档为什么要支持多语言

  • 问题一：主流的开发语言、框架大多都源于欧美，因此其初始文档大多数也是英文的。作为开发者，即使母语不是英语，阅读英文文档也是逐渐成为来一项必备技能。但是开发者在阅读英文版本与母语版本时的阅读效率就因人而异了。幸运的是，这些非英语国家通常会涌现出很多志愿者，帮助翻译官方的英文文档。
  • 问题二：很多人都有个人 blog，尤其是技术人员，他们乐于在自己的 blog 中记录自己遇到的问题及解决方法，这不仅是总结自己的经验，也把知识分享给了他人。但限于他编写blog文章所用的语言，母语是其他语言的人可能无法检索到、或者看不懂他的文章。这限制文章的传播和知识的分享，还限制其他人寻找问题解决方法的便捷性。

我们想要怎样的多语言支持？

  • 翻译质量高：这一点永远是最重要的
  • 方便参考原文
    • 最好在同一页面内显示译文和原文
      • 这样方便我们在发现某一句话翻译得不太对时，查看原文确认
    • 最好不改变原网页页面结构
  • 尽量减少人工参与的工作量
    • 前文提到通常有志愿者帮助翻译软件的官方文档的，但仍存在的困境是由于志愿者不足或者精力有限等问题，导致最新的官方文档并没有得到及时的翻译
    • 有些多语言支持的方案是维护其他语言的页面或网站，这可能增加开发及维护成本
  • 反馈及改善机制要好
    • 即使是目前翻译质量较高的 ChatGPT，也有翻译得不尽如人意的时候
    • 当某个词或者某个句子的翻译质量较低的时候，需要有人工干预、修改、反馈的机制
    • 翻译器需要能够基于用户反馈的翻译内容进行学习，改善其翻译能力

目前主流的多语言支持方式

Google 翻译

Google 翻译可以直接在网站内部集成：

综合评价（评分0～5分）

评价项 评分 备注
翻译质量高 2 现阶段 Google 翻译的质量不高
方便参考原文 3 需要通过菜单来回切换，或者打开两个网页
人工参与的工作量少 4 这种方式是最为简单粗暴、成本最低，因此最为常见
反馈及改善机制 0.5 当前用户几乎无法反馈翻译结果

多语言页面切换

通过语言切换按钮来切换到当前页面的其他语言版本，实际上是另一个URL不同的页面。这种方式实际上与网站内部集成 Google 翻译类似。

综合评价（评分0～5分）

评价项 评分 备注
翻译质量高 4.5+ 如上图中的例子，这类官方文档应该是在机器翻译的基础上，加上人工校对后翻译的
方便参考原文 3 需要通过菜单来回切换，或者打开两个网页
人工参与的工作量少 1
  • 前面提到，机器翻译+校对，需要一定的人工参与
  • 如上图中的例子，Python 3.12.0a7 是官方最新dev版本，新版本中会有基于上一版本文档的修改内容和新增内容，这些内容在一段时间内无法及时翻译。毕竟志愿者的数量和精力也是有限的
  • 维护独立的网页也需要一定的工作量
反馈及改善机制 1.5 类似 Python 这种开源软件，它的文档一般都是以单独的项目维护的，如果用户想对翻译内容进行修正，一般需要是通过 issue tracker 来反馈，可以参考 Python 官方文档的 Dealing with Bugs 一节

建立不同语言的网站

有的软件的不同语言的文档放在不同的网站域名下，有些放在不同的子域名下。这种方式上面那种多语言页面的切换相比，维护web server的工作量更高。

综合评价（评分0～5分）

评价项 评分 备注
翻译质量高 4.5+ 跟上一节提到的情况类似
方便参考原文 2? 根据 Angular 官网的例子，在某一个文档页面内，不能直接切换到其他语言的网站的对应页面（Angular.cn有它独特的解决办法，后文将详细说明）
人工参与的工作量少 0.5 工作量跟上一节提到的维护不同语言的网页差不多，但多了维护额外的 web server 的成本
反馈及改善机制 1.5 跟上一节提到的情况类似

题外话——阅读外文文档的辅助翻译工具

前文是站在技术软件的文档网站开发者角度，讨论支持多语言的各种可选技术方案。

另一方面，作为文档阅读者，我们总是提倡阅读原版的外文文档，这时就可以借助辅助翻译工具提升我们的阅读效率。

虽然鉴于本文标题这方面算是题外话了，但是还是有必要聊一下。

Chrome 中的 Google Translate

在客户端（如浏览器）中利用内置功能/插件来调用，它的实现方式、翻译效果与网站端引入Google翻译的方式类似。

划词翻译

我在阅读原版官方文档、学习日语或英语时，经常用到划词翻译工具，来查阅不认识的单词。

有些划词工具结合 Anki 可以在划词查询以后直接制作 Anki 卡片，用于单词记忆。关于 Anki 这款强大的记忆软件，以后我会写文章专门介绍。

Online Dictionary Helper

Online Dictionary Helper 内置了很多词典，支持了多种主流语言与英文、中文之间的互译，除了单词，它也支持对句子的划词翻译，只不过翻译质量不高。它可以划词直接制作Anki卡片。

Yomichan

Yomichan 主要用于日语的单词查询，可以下载各类词典，但都是释义都是英文的。它不支持对句子的划词翻译。它也可以划词直接制作Anki卡片。

openai-translator

openai-translator 是利用最近大火的 ChatGPT 来翻译的，它具有如下特点：

  • 优点
    • 翻译质量比较高：由于 ChatGPT 学习了大量的文献、文档、网页等资料，因此它的翻译准确度相对较高。
    • 有一定的反馈及改善机制：在翻译质量欠佳时可以使用polishing按钮，要求重新翻译，通常情况下都能得到一个更好的版本。
  • 缺点
    • 隐私及安全问题：这是老生常谈的问题了，划词翻译会将我们正在看的内容泄露给 ChatGPT
    • 划词翻译限制了翻译能力：ChatGPT 作为翻译器的时候，最强大的地方是在于它根据对文章上下文的分析和学习，提升整篇文章的学习质量。但划词翻译相当于只提供给了它片面的内容，虽然它能基于云端的历史学习经验来进行翻译，但效果肯定不如提供全文给它后得到的翻译效果好。
    • 反馈及改善机制有待提高：如果使用官方版本的ChatGPT来翻译某些文字，翻译质量不高的时候，我们可以反馈给它，并给出更好的翻译建议，有助于改善它的翻译能力。但是 openai-translator 只能使用 polishing 按钮让 ChatGPT “重新翻译”，不能 “告诉它应该如何更好地翻译”

谈谈技术文档多语言支持的最佳实践

回到主题，站在技术软件的文档网站开发者角度，让网站支持多语言的最佳实践是什么？

根据前文我们可以了解到，即需要尽可能满足如下需求：

  1. 翻译质量高
  2. 方便参考原文
  3. 尽量减少人工参与的工作量
  4. 反馈及改善机制要好

先聊聊有哪些已有的产品已经比较好的解决了上述的问题

angular.cn 的最佳实践

2. 方便参考原文 比较难以解决，目前我见过的各类翻译方案中，只有 angular.cn 用巧妙的方式解决了这一问题。

从图中可以看到，angular.cn 的文档中，用鼠标单击段落，会显示英文原文，非常方便对比参考，在对中文的翻译意思模棱两可的时候相当有用。

而 angular.jp 没有实现这种功能，所以我猜测是 angular.cn 网站的维护者自己的灵感。查阅了 angular-cn 文档项目的 issue，发现确实是这样的，作者也介绍了实现的思路。查看了一个 markdown 的源文件，原文和译文确实如作者的意思，是写在一个文档里的。

ChatGPT 带来的希望

angular.cn 的方式很好地解决了 2. 方便参考原文 的问题，而 ChatGPT 的横空出世，能够较好地解决问题 1. 翻译质量高 和 3. 尽量减少人工参与的工作量，但它在 4. 反馈及改善机制要好 这一点上还有一定的局限性，原因我们在介绍 openai-translator 的时候已经聊过。

最佳实践之我见

要做到最佳实践，则需要把前文提到的4点做好，目前我接触到的成品里还没有都能够做好的，如果你知道欢迎评论分享。

目前看整体上较为理想的还是 openai-translator，虽然它是基于用户端的插件，但是从前文讨论过的 Google 翻译的网站端集成以及浏览器插件的相似性可知，其实他们在技术实现上相差无几，区别仅在于调用外部API翻译是在Web Server端做还是在用户的浏览器端做。

现在，可以讨论一下我对最佳实践的详细看法了，这里将不再区分服务器端及用户端：

  1. 翻译质量高：调用 ChatGPT API 等较为先进工具来翻译
  2. 方便参考原文：需要结合 Google 翻译及 angular.cn 的方式。
    • Google 翻译强大之处在于，它在翻译的时候能够精准地仅仅替换网页中的文字，而对网页源码中的HTML元素或者Javascript不做修改。
      • Google之所以能做是有从网页中标记和提取文字的先天技术优势
        • Google 是做搜索引擎起家的，其背后有强大的爬虫支持，这使得 Google 有丰富地从网页中提取文字部分的经验
        • Google 开发了 Chrome 浏览器，浏览器的核心功能就是做 DOM 解析和渲染，这又使得 Google 在网页中文字的标记和提取上积累了丰富的经验
      • 如果我们自己想要实现这种效果，其中的技术难度不可忽视，好在 Chromium 是开源的可供参考。此外，我猜测应该也存在专门解决这个问题的其他开源库
    • angular.cn 的鼠标单击译文段落可以切换原文的隐藏和显示，这个方式非常先进。
    • 如何结合上述两种方式
      1. 利用类似Chrome的能力，解析DOM、提取文字
      2. （可选）将所有相关网页直接发送给ChatGPT进行学习
        • 这一步对提升ChatGPT的整体翻译效果很有必要，前文做过相关讨论
        • 通常可以把整个网站都发送给 ChatGPT，让它阅读网站内的所有内容，并做好翻译后续指定网页内容的准备
      3. 将当前网页文字提取后调用 ChatGPT 进行翻译
      4. 复制原始 DOM 元素并添加到原DOM元素之前，替换其中的文字为翻译后的文字。
      5. 利用 CSS 隐藏原始 DOM 元素
      6. 利用 CSS 和 Javascript 实现：当用户点击译文的DOM原始时，显示原始DOM
    • 以上的 1～6 步其实也可以完全由 ChatGPT 来做，但需要对它做相应的训练
      • 因为像 Google 一样，ChatGPT 肯定也有强大的网页DOM解析及文字提取功能
  3. 尽量减少人工参与的工作量：如果 1、2、4 点能够做好，这一点就显得自然而然、水到渠成了
  4. 反馈及改善机制要好：要充分利用 ChatGPT 的学习和自我改善的能力。这里继续在 2 中的 结合两种方式 的对技术实现方式讨论。
    1. 当某个译文DOM元素中的译文存在翻译欠妥的情况，应该能够运行用户选择相关文字，然后呼出 ChatGPT 的对话框，向它反馈发现的问题，也可以更进一步告诉它正确的翻译方式，这样有助于它的改善
    2. 在我们给ChatGPT 指出问题、给出翻译指导后，需要让ChatGPT 重新翻译，然后使用新的译文更新相关的DOM元素，其中经过优化的译文部分可以高亮显示

结束语

ChatGPT 的问世给开发者带来了巨大的方便，也为文档翻译和外文文档阅读带来了巨大的改变。因为它能做的远不止这些，有人担心它会让从事某些职业的人失业，我认为目前大可不必担心，去熟悉他、善用它只会让我们如虎添翼。

如果某一天 AI 也能思考出最佳实践并自动实现它，那时候它可能就不只是能淘汰人，而是能消灭人类了:)