如何帮助翻译文档内容

注解

MegEngine 文档翻译工作目前通过 Crowdin 平台进行协作,与 GitHub 自动集成。

对于参与文档翻译的人员,对以下目录结构有一定了解将有所帮助:

Documentation
├── source
├── locales               # Sphinx 多语言支持,内部结构和 source 高度对齐   ├── zh-CN             # 中文:主要需要翻译 API 的 Docstring 部分   └── en                # 英文:需要翻译除 API Docstring 外的全部内容
...

基本原理

MegEngine 文档使用 Sphinx 官方推荐的 国际化 方式实现多语言支持。

整个翻译内容的生成流程如下( 翻译人员通常只需要关注第 4 步 ):

  1. source 文件夹中存放着所有的文档内容,以 .rst 格式提供。

  2. 通过运行下面的命令,将从 .rst 文件中提取出可被翻译的消息(message)模版:

    make gettext
    

    生成的 .pot 文件将被放在 build/gettext 目录内。

  3. 根据需要支持的语言,生成对应的 .po 文件:

    sphinx-intl update -p build/gettext -l zh_CN -l en
    

    上面的代码将为我们生成中文和英文两个版本的 .po 文件,分别位于:

    • /locales/zh_CN/LC_MESSAGES/

    • /locales/en/LC_MESSAGES/

  4. 翻译人员需要做的就是翻译 .po 文件中的内容。样例如下:

    #: locales/zh_CN/LC_MESSAGES/example.rst:37
    msgid "Welcome to use MegEngine."
    msgstr "欢迎使用 MegEngine."
    
  5. 生成翻译后的文档( LANGUAGE 参数默认为 zh-CN ):

    make LANGUAGE="zh_CN" html  # 中文
    make LANGUAGE="en" html     # 英文
    

现在你可以通过下面提到的 Crowdin 平台来完成对 .po 文件的翻译,而不需要通过 GitHub.

使用 Crowdin 进行翻译

传统的软件翻译流程通常需要面临审核校对和信息同步等难题, 通过 Crowdin 则可以享受到:

  • 开放参与。任何人都可以注册账号,加入团队,翻译贡献。 每个人的翻译记录都会被记录下来,而不会被覆盖或丢弃。 贡献者之间相互审核建议,选择最优的翻译。

  • 透明运作。任何操作都会记录在活动日志当中,有不当翻译或者蓄意破坏很容易被发现并撤销。 翻译人员可以相互讨论提问,提供单独的讨论板块。

  • 进度清晰。当有新的内容需要翻译时,或对原始内容进行修改后,能在第一时间被监控到。

  • 记忆系统。可以根据已有翻译内容给出翻译建议,也可使用主流神经翻译接口辅助建议。

  • 自动集成。更新的翻译内容将自动通过集成系统同步到 GitHub 特定分支,再由人工进行合入。

更多特性请参考:https://crowdin.com/features

加入 MegEngine 翻译项目

你需要注册一个 Crowdin 账户, 进入 MegEngine 项目页面 后可以看到语言选项卡和整体进度:

Chinese Simplified

由于 Sphinx 生成网站时使用 Python Docstring 提取 API 文档内容, 源代码均为英文,因此这部分内容依旧为英文,我们需要将其翻译成中文。

English (以及其它语言)

与上情况相反:除 Python Docstring 外,所有文档原文内容均为中文, 因此我们需要将这些内容翻译成指定语言。(通常我们会提供机器翻译版本作为参考)

选择语言后,可以看到多个需要翻译的文件。每个翻译文件和文件夹都有一个翻译进度。 蓝色条代表已经翻译,绿色条代表已经审核。同一条目可以有多条翻译建议(Suggestion)。 翻译者和审核者可以通过投票来表态,最终导出被审核通过的翻译(如果没有审核,则会选择最近的翻译建议)。

Crowdin 不可用时的做法

当遇到 Crowdin 平台不可用时,我们可以使用最原始的方式来直接维护 .po 文件。

假设你发现 reference/api/megengine.functional.add.html 对应的 API Docstring 部分内容翻译有误/没有翻译,标准的处理流程应该如下:

  1. 判断 .po 文件位置(在这个例子中,属于 API Docstring 英文翻译中文的情况): locales/zh_CN/LC_MESSAGES/reference/api/megengine.functional.add.po

  2. 根据 msgstr 找到对应位置,根据 msgid 原文修改 msgstr 为正确内容;

  3. 按照 Git 工作流向 Documentation 库发起 Pull Request.

更多细节请参考 如何为文档做贡献Commit message 书写指南

翻译注意事项

  • 语法和排版规范可参考 Sphinx reStructuredText 语法入门MegEngine 文档风格指南

  • 不要破坏原有的语法格式,正确示范为:

    #: locales/zh_CN/LC_MESSAGES/example.rst:6
    msgid "A :py:class:`~.megengine.Tensor` object"
    msgstr "一个 :py:class:`~.megengine.Tensor` 对象"
    

    警告

    Sphinx reStructuredText 语法与周围文本内容之间的空格是 必需的 ,不然会以文本形式进行渲染 。 而在 reStructuredText 语法内部,不该出现空格的地方绝对不能出现空格 ,谨记格式的重要性。 在对 API 相关内容进行翻译时尤其需要注重这一点,否则将牵一发而动全身。

  • 不要自行加入新的 Sphinx reStructuredText 语法,翻译程序将会检测到前后数量不一致。

  • 不要丢掉原有标点符号,正确示范为:

    #: locales/zh_CN/LC_MESSAGES/example.rst:6
    msgid "Method:"
    msgstr "方法:"
    

    当然,多出奇怪的符号也是不允许的。

基本要领

  1. 简洁规范。

  2. 忠实原文。

  3. 用语一致。

  4. 易于使用

补充细节说明

  • 中英文之间有且只能有一个空格作为分隔;

  • 优先使用全角标点符号(包括逗号、句号、冒号、分号和问号);

  • 遇到特定英文(要求不译)结束,则后跟使用英文标点符号 ——

    • 绝大部分软件名字都是不翻译的,直接使用英文即可;

    • 项目或组织名称,一般也不进行翻译;

    • 通用的英文缩写,或没有正式中文译文的名词,不需要翻译;

  • 不论中英文,统一使用中文括号()包裹;

  • 按回车造成的换行,是 PO 文件里代码换行。 Crowdin 都能很好地自动换行,因此手动去折行并不是必要的。 即使是翻译时看到英文是折行的,中文也不一定需要折行;