PEP 545 – Python 文档翻译

作者:: Julien Palard <julien at palard.fr>，Inada Naoki <songofacandy at gmail.com>，Victor Stinner <vstinner at python.org>
状态:: 最终版
类型:: 流程
创建:: 2017年3月4日
决议:: Python-Dev 邮件

摘要

本 PEP 的目的是使现有的 Python 文档翻译更容易访问和发现。通过这样做，我们希望吸引和激励新的翻译人员和新的翻译。

翻译后的文档将托管在 python.org 上。两个活跃的翻译团队的示例

https://docs.pythonlang.cn/fr/: 法语
https://docs.pythonlang.cn/ja/: 日语

https://docs.pythonlang.cn/en/ 将重定向到 https://docs.pythonlang.cn/。

翻译后的文档源代码将托管在 GitHub 上的 Python 组织中：https://github.com/python/。贡献者必须接受文档贡献协议。

动机

在 freenode 上的法语 #python-fr IRC 频道中，经常会遇到不会说英语的人，因此无法阅读 Python 官方文档。Python 想要广泛地提供给任何语言的所有用户：这也是 Python 3 支持任何非 ASCII 标识符的原因：PEP 3131

至少有 4 组人正在将 Python 文档翻译成他们的母语（法语 [16] [17] [18]、日语 [19] [20]、西班牙语 [21]、匈牙利语 [26] [27]），即使他们的翻译在 d.p.o 上不可见。其他不太明显且组织性较差的群体也在翻译文档，我们听说过俄语 [25]、中文和韩语。我们尚未发现的其他语言也可能存在。本 PEP 定义了描述如何将翻译移动到 docs.python.org 上的规则，以便开发人员、新手和潜在翻译人员可以轻松找到它们。

日语团队（截至 2017 年 3 月）已翻译了约 80% 的文档，法语团队约 20%。2016 年，法语翻译从 6% 上升到 23% [13]，共有 7 位贡献者 [14]，证明翻译团队的速度可以快于文档变化的速度。

引用 Xiang Zhang 关于中文翻译的内容

我见过几个小组尝试翻译我们官方文档的一部分。但他们的努力分散且很快就会丢失，因为他们没有组织起来朝着一个共同的结果努力，他们的结果散落在网络上的任何地方，难以找到。一个官方的翻译可以帮助缓解这个问题。

基本原理

翻译

问题跟踪器

考虑到关于翻译的问题可能用翻译语言编写，这可以被认为是噪音，但至少是不一致的，问题应该放在 bugs.python.org (b.p.o) 之外。

由于所有翻译都必须拥有自己的 GitHub 项目（请参阅 PO 文件存储库），因此它们必须使用关联的 GitHub 问题跟踪器。

考虑到任何语言编写的翻译问题引起的噪音可能会超出所有警告并出现在 b.p.o 中，需要进行分类。考虑到翻译已经存在并且实际上不是 b.p.o 中的噪音来源，因此不应预期会有大量无法管理的工作。考虑到 Xiang Zhang 和 Victor Stinner 已经在进行分类，并且 Julien Palard 愿意帮助完成这项任务，因此不应预期 b.p.o 中会出现噪音。

此外，语言团队协调员（请参阅语言团队）应该通过在必要时用问题作者的语言正确指示正确的跟踪器来帮助分类 b.p.o。

分支

翻译团队应专注于最新的稳定版本，并使用工具（脚本、翻译记忆等）将一个分支中完成的翻译自动翻译到其他分支。

注意

翻译记忆是一种包含先前翻译的段落（甚至已删除的段落）的数据库。另请参阅 Sphinx 国际化。

将翻译的三个当前稳定分支是 [12]：2.7、3.5 和 3.6。需要修改构建旧分支文档的脚本以支持翻译 [12]，而这些分支现在仅接受安全修复。

开发分支 (main) 的翻译优先级应该低于稳定分支。但 docsbuild-scripts 应该无论如何都构建它，以便团队可以对其进行处理，为下一个版本做好准备。

托管

域名、内容协商和 URL

可以通过更改以下一项来识别不同的翻译：国家代码顶级域名 (CCTLD)、路径段、子域名或内容协商。

为每个翻译购买 CCTLD 成本高昂、耗时，并且当已注册时有时几乎不可能，因此应避免此解决方案。

使用像“es.docs.python.org”或“docs.es.python.org”这样的子域名是可能的，但会造成混淆（“是 es.docs.python.org 还是 docs.es.python.org？”）。子域名中的连字符（如 pt-br.doc.python.org）并不常见，SEOMoz [23] 将连字符的存在与负面因素相关联。子域名中使用下划线被 RFC 1123 的第 2.1 节禁止。最后，使用子域名意味着为每种语言创建 TLS 证书。这不仅需要更多维护，而且如果我们像版本切换器一样希望进行预检以检查给定版本中是否存在翻译，也会在语言切换器中造成问题：预检可能会被同源策略阻止。通配符 TLS 证书非常昂贵。

使用内容协商（请求中的 HTTP 标头 Accept-Language 和 Vary: Accept-Language）会导致糟糕的用户体验，用户无法轻松更改语言。根据 Mozilla 的说法：“当服务器无法通过其他方式（如特定 URL，由明确的用户决策控制）确定语言时，此标头是一个提示。” [24]。由于我们希望能够轻松更改语言，因此不应将内容协商用作主要语言确定方法，因此我们需要其他方法。

最后一个解决方案是使用 URL 路径，它看起来可读性强，允许轻松地在一种语言和另一种语言之间切换，并且可以很好地接受连字符。通常类似于：“docs.python.org/de/”或使用连字符：“docs.python.org/pt-BR/”。

至于版本，sphinx-doc 不支持为多种语言编译，因此我们将拥有以路径为根的完整构建，就像我们已经在版本中所做的那样。

因此，我们可以有“docs.python.org/de/3.6/”或“docs.python.org/3.6/de/”。出现的问题是：“语言包含多个版本，还是版本包含多种语言？”。由于版本在任何情况下都存在，并且给定版本的翻译可能存在也可能不存在，因此我们可能更喜欢“docs.python.org/3.6/de/”，但这样做会将语言分散到各个地方。使用“/de/3.6/”更清晰，表示：“/de/ 下的所有内容都用德语编写”。在末尾放置版本也是文档阅读者养成的习惯：他们喜欢通过更改路径末尾来轻松更改版本。

因此，我们应该使用以下模式：“docs.python.org/LANGUAGE_TAG/VERSION/”。

当前文档不会移动到“/en/”，而是“docs.python.org/en/”将重定向到“docs.python.org”。

语言标签

语言标签的常用表示法是基于 ISO 639 的 IETF 语言标签 [4]，尽管 gettext 使用带下划线 (例如：pt_BR) 的 ISO 639 标签而不是连字符来连接标签 [5] (例如：pt-BR)。IETF 语言标签示例：fr（法语）、ja（日语）、pt-BR（1943 年的正字法 - 巴西官方语言）。

在 URL 中看到连字符而不是下划线更为常见 [6]，因此我们应该使用 IETF 语言标签，即使 sphinx 在内部使用 gettext：URL 不应泄露底层实现。

在 URL 中看到大写字母并不常见，docs.python.org 也没有使用任何大写字母，因此它可能会通过吸引眼球来损害可读性，例如：“https://docs.pythonlang.cn/pt-BR/3.6/library/stdtypes.html”。RFC 5646#section-2.1.1（用于识别语言的标签 (IETF)）第 2.1 节指出标签不区分大小写。由于 RFC 允许使用小写，并且它可以增强可读性，因此我们应该使用小写标签，如 pt-br。

当区域子标签不添加区分信息时，我们可以删除它，例如：“de-DE”或“fr-FR”。（虽然它可能是有意义的，分别表示“在德国所说的德语”和“在法国所说的法语”）。但当区域子标签确实添加信息时，例如“pt-BR”或“在巴西所说的葡萄牙语”，则应保留它。

因此，我们应该使用 IETF 语言标签，小写，如 /fr/、/pt-br/、/de/ 等。

获取和构建翻译

目前，docsbuild-scripts 正在构建文档[8]。这些脚本应该被修改以获取和构建翻译。

构建新的翻译就像构建新的版本一样，因此，虽然我们增加了复杂性，但并没有那么多。

两个步骤应该能够分别配置：构建一种新的语言，以及将其添加到语言切换器中。这允许在“我们接受了这种语言”和“它被翻译得足够好以公开发布”之间进行过渡。在此步骤期间，翻译人员可以在 d.p.o 上查看他们的修改，而无需在本地构建文档。

从翻译存储库中，只有.po文件应该由 docsbuild-script 打开，以将攻击面和可能的错误来源降到最低。这意味着没有翻译可以修补 sphinx 以宣传他们的翻译工具。（此特定功能应该由 sphinx 处理[9]）。

社区

邮件列表

doc-sig 邮件列表将用于讨论翻译文档的跨语言更改。

还有一个 i18n-sig 列表，但它更侧重于 i18n API[1]，而不是翻译 Python 文档。

聊天

由于 Python 社区在 IRC 上非常活跃，我们应该在 freenode 上创建一个新的 IRC 频道，通常为 #python-doc，以与邮件列表名称保持一致。

每个语言协调员可以组织自己的团队，甚至可以选择其他聊天系统，如果本地使用要求这样做。由于本地团队将使用他们的母语进行写作，我们不希望每个团队都在一个频道中。本地团队重用他们本地的频道，例如法语翻译人员的“#python-fr”，也是很自然的。

PO 文件存储库

考虑到每个翻译团队可能希望使用不同的翻译工具，并且这些工具应该易于与 git 同步，所有翻译都应该通过 git 存储库公开其.po文件。

考虑到每个翻译都将通过 git 存储库公开，并且 Python 已迁移到 GitHub，翻译将托管在 GitHub 上。

为了保持一致性和可发现性，所有翻译都应位于同一个 GitHub 组织中，并根据通用模式命名。

鉴于我们希望翻译成为官方的，并且 Python 已经拥有一个 GitHub 组织，因此翻译应作为Python GitHub 组织的项目托管。

为了保持一致性，翻译存储库应命名为python-docs-LANGUAGE_TAG[22]，使用路径中使用的语言标签：如果冗余则不使用区域子标签，并且小写。

docsbuild-scripts 可以通过拒绝从 Python 组织或错误命名的存储库外部获取来强制执行此规则。

CLA 机器人可以在翻译存储库上使用，但效果有限，因为本地协调员可能会将自己与来自外部工具（如 transifex）的翻译同步，并在过程中丢失对谁翻译什么的跟踪。

版本可以托管在不同的存储库、不同的目录或不同的分支上。将它们存储在不同的存储库中可能会污染 Python GitHub 组织。由于使用分支来分离版本是典型且自然的，因此应该使用分支来做到这一点。

翻译工具

大多数翻译工作实际上是在 Transifex 上完成的[15]。

以后可能会使用其他工具，例如https://pontoon.mozilla.org/ 和http://zanata.org/。

文档贡献协议

文档确实需要翻译人员的许可，因为它涉及到对想法的表达的创造性。

有多种解决方案，引用 PSF 的 Van Lindberg 对此主题的回答

文档应该要么分配版权，要么在 CCO 下。宽松的软件许可证（如 Apache 或 MIT）也可以完成工作，尽管它并不完全适合任务。

翻译人员应该要么签署协议，要么提交翻译的许可声明。

我们应该在项目页面上有一个邀请人们在定义的许可下贡献的邀请，并通过他们的贡献行为来定义接受。例如

“通过将此项目发布在 Transifex 上并邀请您参与，我们正在提议一项协议，即您将以 CC0 许可证的形式为 PSF 提供您的翻译。作为回报，您可以注意到您是您翻译的部分的翻译者。您通过将您的作品提交给 PSF 以纳入文档中来表示接受此协议。”

看起来拥有“文档贡献协议”是我们能做的最简单的事情，因为我们可以在不同的上下文中使用多种方式（GitHub 机器人、邀请页面等）来确保贡献者同意它。

语言团队

每个语言团队应该有一位协调员负责

管理团队。
选择和管理团队将使用的工具（聊天、邮件列表等）。
确保贡献者理解并同意文档贡献协议。
确保质量（语法、词汇、一致性、过滤垃圾邮件、广告等）。
将发布在 b.p.o 上的问题重定向到该语言的正确 GitHub 问题跟踪器。

备选方案

简化英语

可以像维基百科那样引入“简化英语”版本[10]，如 python-dev 中所讨论的[11]，针对英语学习者和儿童。

优点：它产生了一个单一的翻译，理论上每个人都可以阅读，并且可以由当前维护者审查。

缺点：可能会丢失微妙的细节，并且如维基百科所述，很难找到从英语到英语的翻译人员

> 维基百科英文版有 500 万篇文章，由近 14 万活跃用户撰写；瑞典语维基百科几乎一样大，300 万篇文章来自仅 3000 名活跃用户；但简易英语维基百科只有 12.3 万篇文章和 871 名活跃用户。这比世界语的文章还少！

更改

获取文档贡献协议

文档贡献协议必须由 PSF 编写，然后列在https://pythonlang.cn/psf/contrib/，并有自己的页面，如https://pythonlang.cn/psf/contrib/doc-contrib-form/。

迁移 GitHub 存储库

我们（本 PEP 的作者）已经拥有法语和日语 Git 存储库，因此将它们移动到 Python 文档组织不会有任何问题。但是，我们将遵循新的翻译流程。

为文档贡献协议设置 GitHub 机器人

为了帮助确保来自 GitHub 的贡献者已签署文档贡献协议，我们可以在迁移的存储库上设置针对此协议定制的“The Knights Who Say Ni”GitHub 机器人[28]。

修补 docsbuild-scripts 以编译翻译

Docsbuild-script 必须修补以

列出要构建的语言标签以及要构建的分支。
列出要在语言切换器中显示的语言标签。
通过格式化github.com:python/python-docs-{language_tag}.git查找翻译存储库（请参阅Po 文件的存储库）。
为每个分支和每种语言构建翻译。

修补的 docsbuild-scripts 只能打开翻译存储库中的.po文件。

NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is
maintained using a global network of volunteers. By posting this
project on Transifex, GitHub, and other public places, and inviting
you to participate, we are proposing an agreement that you will
provide your improvements to Python's documentation or the translation
of Python's documentation for the PSF's use under the CC0 license
(available at
`https://creativecommons.org/publicdomain/zero/1.0/legalcode`_). In
return, you may publicly claim credit for the portion of the
translation you contributed and if your translation is accepted by the
PSF, you may (but are not required to) submit a patch including an
appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although
nothing in this Documentation Contribution Agreement obligates the PSF
to incorporate your textual contribution, your participation in the
Python community is welcomed and appreciated.

You signify acceptance of this agreement by submitting your work to
the PSF for inclusion in the documentation.