摘要

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

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

http://docs.python.org/fr/: French

http://docs.python.org/ja/: Japanese

http://docs.python.org/en/会重定向到 http://docs.python.org/ 。

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

动机

在 freenode 上的法语＃ python-fr IRC 频道上，并不难遇到因不会说英语而读不懂 Python 官方文档的人。Python 希望被广泛使用无论用户使用哪种语言：这也是 Python 3 支持任何 non-ASCII 的原因： https://www.python.org/dev/peps/pep-3131/#rationale

至少有 4 个团队正在将 Python 文档翻译成他们的母语（法语[16] [17] [18]，日语[19] [20]，西班牙语[21]，匈牙利语[27] [28] ）即使他们的翻译在 d.p.o 上不可见 ,也有其他潜在的和不太有组织的团队也在进行翻译，我们听说过俄语[26]，中文和韩文。其他我们不知道的团队也可能存在。本 PEP 定义了描述如何在 docs.python.org 上发布翻译成果的规则，以便开发人员，新人和潜在翻译人员可以轻松参与。

日本团队已经翻译了约 80 ％的文件（截至 2017 年 3 月），法国队~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 进行分类。

分支

翻译团队应该关注最后的稳定版本，并使用工具（脚本，translation memory......）自动将一个分支中完成的内容转换为其他分支。

####注意

Translation memory 是一种先前翻译过的段落的数据库，甚至是已删除的段落。另见 Sphinx 国际化。

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

开发分支（ master ）的翻译优先级应低于稳定分支。但 docsbuild-scripts 脚本也应该创建它，这样团队可以为下一个版本开始做准备工作。

托管

域名，Content negotiation 和 URL

可以通过更改以下内容之一来访问不同的语言：国家 /地区代码顶级域（ CCTLD ），路径，子域或 Content negotiation。

为每种语言购买 CCTLD 既昂贵又耗时，有些已被抢注，此解决方案应避免使用。

像“ es.docs.python.org ”或“ docs.es.python.org ”这样的子域名是可行的，但使用时会令人困惑（“是 es.docs.python.org 还是 docs.es.python.org ？”）。像 pt-br.doc.python.org 这样的子域中的连字符并不常见，SEOMoz [23]将连字符看作负面因素。 而 RFC1123 [24]第 2.1 节禁止在子域中使用下划线。最后，使用子域需要为每种语言创建 TLS 证书。这不仅需要更多的维护，而且还会导致官方文档语种选择功能出现问题，如果对于版本切换器，我们需要预检给定版本的翻译是否存在：预检可能会被同源策略阻止。而通配符 TLS 证书非常昂贵。

使用 content negotiation （请求中的 HTTP 标头 Accept-Language 和 Vary：Accept-Language ）会导致用户体验不佳，无法轻松更改语言。根据 Mozilla 的说法：“当服务器无法通过其他方式确定语言时，此标头可以作为一种判断依据，而像特定的 URL，用户可以明确地进行控制。” [25]。由于我们希望能够轻松更改语言，因此我们不应将 content negotiation 作主要语言决策，所以还需要其他方式。

最后的解决方案是使用直观的 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 语言标签[3] [4]，尽管 gettext 使用带下划线的 ISO 639 标签（例如：pt_BR ）而不是破折号[5]（例如：pt-BR ） ）。IETF 语言标签的示例：fr （法语），ja （日语），pt-BR （ 1943 年的正交公式 - 巴西官方）。

在 URL [6]中更常见的是破折号而不是下划线，因此我们应该使用 IETF 语言标记，即使 sphinx 在内部使用了 gettext：URL 规则并不意味着公开底层实现。

在 URL 中看到大写字母并不常见，而 docs.python.org 不使用任何大写字母，所以它可能会吸引人的注意力，从而影响可读性，例如：“ https://docs.python.org/pt-BR /3.6/library/stdtypes.html ”。RFC 5646 （标识语言标记（ IETF ））第 2.1 节[7]指出标记不区分大小写。所以 RFC 允许小写，并且它增强了可读性，我们应该使用像 pt-br 这样的小写标签。

当区域子标签没有区别作用时，我们可以删除它，例如：“ de-DE ”或“ fr-FR ”。 （虽然它可能有意义，分别意为“德语在德国使用”和“法语在法国使用”）。但是当区域子标签实际上添加了信息时，例如“ pt-BR ”代表“巴西语中的葡萄牙语”，它应该被保留。

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

获取和建立翻译

目前 docsbuild-scripts 脚本被用于构建文档[8]。修改这些脚本可以获取和构建翻译。

构建新版本翻译就像构建新版本 so 一样，虽然我们增加了复杂性，但并不是那么多。

应该区分两个步骤：构建新语言，将其添加到官方语言列表中。这要求从“我们接受该语种”过渡到“它被翻译到足以公开”。在此过程中，翻译人员可以在 d.p.o 上查看其修改，而无需在本地构建文档。

在翻译的 repositories 中，docsbuild-script 脚本只应该打开.po 文件，以便将攻击面和可能的错误源保持在最低限度。这意味着没有任何翻译可以修补 sphinx 来宣传他们的翻译工具。 （无论如何，这个特定的功能应该由 sphinx 处理[9]）。

社区

邮件列表

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

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

Chat

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

每个语言协调员都可以组织自己的团队，即使本地使用情况要求，也可以选择其他聊天系统。由于本地团队将使用他们的母语编写，我们不要求所有团队都在一个频道中。对于法国翻译来说，使用“＃ python-fr ”等本地频道也是很自然的。

PO 文件 Repository

考虑到每个翻译团队可能想要使用不同的翻译工具，这些工具应该很容易同步到 git，所有翻译都应该通过 git repository 公开他们的.po 文件。

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

为了保持一致性和可发现性，所有翻译应该在同一个 GitHub 组织中，并根据常见模式命名。

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

为了保持一致性，翻译 repositories 应该被称为 python-docs-LANGUAGE_TAG [22]，使用路径中使用的语言标记：如果是 region 子标记冗余则删除，并且使用小写。

docsbuild-scripts 脚本可以通过拒绝在 Python 组织外部或错误命名的 repository 中使用来强制执行此规则。

CLA 机器人可以在翻译 repositories 中使用，但效果有限，因为本地协调员可以将自己与来自外部工具（如 transifex ）的翻译同步，并且无法跟踪谁在翻译过程中的内容。

版本托管的形式可以选择在不同的 repositories，不同的目录或不同的分支上。将它们存储在不同的 repositories 中可能会污染 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 问题跟踪器。