Following system colour scheme - Python 增强提案 Selected dark colour scheme - Python 增强提案 Selected light colour scheme - Python 增强提案

Python 增强提案

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/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],这证明一个翻译团队的速度可以快于文档的更新速度。

引用张翔关于中文翻译的言论:

我看到有几个团队试图翻译我们官方文档的一部分。但他们的努力是分散的,很快就消失了,因为他们没有组织起来朝着一个共同的目标努力,而且他们的成果分散在网络上的任何地方,很难找到。一个官方的翻译可以帮助减轻这种痛苦。

基本原理

翻译

问题跟踪器

考虑到关于翻译的问题可能用翻译语言书写,这可能被认为是噪音,但至少是不一致的,所以问题不应放在 CPython 问题跟踪器中。

由于所有翻译都必须有自己的 GitHub 项目(参见 Po 文件仓库),因此它们必须使用相关的 GitHub 问题跟踪器。

考虑到用任何语言编写的翻译问题可能造成的噪音,尽管有警告,但仍可能出现在问题跟踪器中,因此需要进行分类。考虑到翻译已经存在,并且实际上不是问题跟踪器中的噪音源,预计不会有无法管理的工作量。考虑到张翔和 Victor Stinner 已经在进行分类,并且 Julien Palard 愿意协助此任务,预计问题跟踪器上的噪音不会很大。

此外,语言团队协调员(参见 语言团队)应通过(如有需要)以问题作者的语言,正确指出正确的议题追踪器来协助分类议题追踪器。

分支

翻译团队应专注于最新的稳定版本,并使用工具(脚本、翻译记忆库等)将一个分支中的内容自动翻译到其他分支。

注意

翻译记忆库是一种数据库,存储以前翻译过的段落,甚至是被删除的段落。另请参阅 Sphinx 国际化

最新的稳定分支将被翻译,并且翻译可以传播到其他分支。构建旧分支文档的脚本需要修改以支持翻译 [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-LanguageVary: 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 使用带有下划线的 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.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. 上查看他们的修改,而无需在本地构建文档。

从翻译仓库中,docsbuild-script 应该只打开 .po 文件,以尽量减少攻击面和可能的 bug 源。这意味着任何翻译都不能修补 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/

python-docs-translations

python-docs-translations GitHub 组织是许多有用的翻译工具的所在地,例如翻译仪表板

文档贡献协议

文档确实需要译者的许可,因为它涉及思想表达的创造性。

有多种解决方案,引用 PSF 的 Van Lindberg 关于该主题的言论:

  1. 文档应具有版权分配或置于 CCO 之下。宽松的软件许可证(如 Apache 或 MIT)也能完成任务,尽管它不太适合该任务。
  2. 译者应签署协议或提交附带翻译的许可证声明。
  3. 我们应该在项目页面上邀请人们在明确定义的许可证下贡献,并将其贡献行为视为接受。例如:

“通过在 Transifex 上发布此项目并邀请您参与,我们提出了一项协议,您将根据 CC0 许可证为 PSF 提供您的翻译。作为回报,您可以注明您是您翻译部分的译者。您通过向 PSF 提交您的作品以纳入文档中来表示接受本协议。”

看起来拥有“文档贡献协议”是我们能做的最简单的事情,因为我们可以通过多种方式(GitHub 机器人、邀请页面等)在不同的背景下确保贡献者同意该协议。

语言团队

每个语言团队应有一名协调员负责:

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

备选方案

简体英文

可以引入一个“简化英语”版本,就像维基百科所做的那样 [10],正如 python-dev 上讨论的 [11],面向英语学习者和儿童。

优点:它产生单一翻译,理论上每个人都可读,并且当前维护者可审查。

缺点:细微的细节可能会丢失,而且正如维基百科所说,从英语到英语的翻译者可能很难找到:

> 主英语维基百科有500万篇文章,由近14万活跃用户撰写;瑞典语维基百科也差不多大,300万篇文章只有3千活跃用户;但简易英语维基百科只有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 文件。

在开发指南中列出协调员

在开发指南中添加一页或一个包含空协调员列表的部分,每个新的协调员都将添加到此列表中。

创建 sphinx-doc 语言切换器

与版本切换器高度相似,必须实现一个语言切换器。此语言切换器必须可配置以隐藏或显示给定语言。

语言切换器只需更新或添加语言段到路径,就像当前的版本切换器一样。与版本切换器不同,不需要预检,因为目标页面始终存在(翻译不会添加或删除页面)。未翻译(但存在)的页面仍然存在,但它们应该以这种方式呈现,参见 增强未翻译和模糊翻译的渲染

更新 sphinx-doc 版本切换器

version_switch.js 中版本切换器的 patch_url 函数必须更新,以理解并允许路径中存在语言段。

增强未翻译和模糊翻译的渲染

这是一个已打开的 Sphinx 问题 [9],但我们需要它,所以我们必须解决它。已翻译、模糊和未翻译的段落应该有所区别。(模糊段落必须警告读者他正在阅读的内容可能已过时。)

新翻译程序

指定协调员

第一步是指定一名协调员,参见 语言团队。协调员必须签署 CLA。

协调员应被添加到开发指南的翻译协调员列表中。

创建 GitHub 仓库

在 Python GitHub 组织中创建一个名为“python-docs-{LANGUAGE_TAG}”的仓库(IETF 语言标签,不带冗余区域子标签,带连字符,小写)。(参见 Po 文件仓库),并授予语言协调员该仓库的推送权限。

设置文档贡献协议

README 文件应清晰显示以下文档贡献协议:

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.

在 docsbuild-scripts 中添加对翻译的支持

一旦翻译提交了第一个提交,更新 docsbuild-scripts 配置以构建翻译(但不将其显示在语言切换器中)。

将翻译添加到语言切换器

一旦翻译达到以下标准,

  • 100% 的 bugs.html 页面,并带有指向语言仓库问题跟踪器的正确链接。
  • 100% 的教程。
  • 100% 的库/函数(内置)。

翻译可以添加到语言切换器中。

以往讨论

[Python-ideas] 交叉链接文档翻译 (2016年1月)

[Python-Dev] 翻译的 Python 文档 (2016年2月)

[Python-ideas] https://docs.pythonlang.cn/fr/ ? (2016年3月)

参考资料

[2] [Doc-SIG] Python 文档的本地化 (https://mail.python.org/pipermail/doc-sig/2013-September/003948.html)


来源:https://github.com/python/peps/blob/main/peps/pep-0545.rst

最后修改:2025-03-09 21:32:47 GMT