V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
推荐学习书目
Learn Python the Hard Way
Python Sites
PyPI - Python Package Index
http://diveintopython.org/toc/index.html
Pocoo
值得关注的项目
PyPy
Celery
Jinja2
Read the Docs
gevent
pyenv
virtualenv
Stackless Python
Beautiful Soup
结巴中文分词
Green Unicorn
Sentry
Shovel
Pyflakes
pytest
Python 编程
pep8 Checker
Styles
PEP 8
Google Python Style Guide
Code Style from The Hitchhiker's Guide
anuan
V2EX  ›  Python

简单翻译了一下 PEP545 流程挺复杂的

  •  2
     
  •   anuan · 2018-08-10 11:00:44 +08:00 · 2329 次点击
    这是一个创建于 2057 天前的主题,其中的信息可能已经有所发展或是发生改变。

    摘要

    本 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 问题跟踪器。

    7 条回复    2018-08-10 17:15:29 +08:00
    congeec
        1
    congeec  
       2018-08-10 11:12:35 +08:00   ❤️ 1
    我来引战。楼主比前两天那个发帖号召翻译 python 3.7 文档的靠谱多了
    我要给楼主铜币表示支持
    whx20202
        2
    whx20202  
       2018-08-10 11:16:03 +08:00
    给力,可惜技术水平达不到
    whx20202
        3
    whx20202  
       2018-08-10 11:16:16 +08:00
    @whx20202 #2 我是说我自己的。。。
    blodside
        4
    blodside  
       2018-08-10 11:20:35 +08:00
    我也要给楼主铜币表示支持
    orangeade
        5
    orangeade  
       2018-08-10 11:40:04 +08:00
    支持,如果业余时间多我也想参加
    yiqiao
        6
    yiqiao  
       2018-08-10 11:44:42 +08:00
    @congeec 号召的已经翻译完了哈哈哈
    anuan
        7
    anuan  
    OP
       2018-08-10 17:15:29 +08:00
    我不搞了
    官方的翻译在 https://www.transifex.com/python-doc/python-newest/
    但我不知道怎么用
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2724 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 15:39 · PVG 23:39 · LAX 08:39 · JFK 11:39
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.