PEP 545 - Python文档翻译

简介待添加

完成度:
已提交:78%,已审核:66%
译者列表:
0B7UcB8-1e0BWC50u-6pU00hgkb-530Bh9BAX-5U
主创团队:
专栏主:0B7UcB8-1e
管理员:0B7UcB8-1e
责任编辑:(认领本文成为编辑)

申请

相关链接:
目录原链

参与翻译


翻译要求

得体 传神 有内涵

  • PEP 545 -- Python Documentation Translations

    PEP 545 - Python文档翻译

  • Abstract

    摘要

  • The intent of this PEP is to make existing translations of the Python Documentation more accessible and discoverable. By doing so, we hope to attract and motivate new translators and new translations.

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

  • Translated documentation will be hosted on python.org. Examples of two active translation teams:

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

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

    -

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

    -

  • http://docs.python.org/en/ will redirect to http://docs.python.org/.

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

  • Sources of translated documentation will be hosted in the Python organization on GitHub: https://github.com/python/. Contributors will have to accept a Documentation Contribution Agreement.

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

  • Motivation

    动机

  • On the French #python-fr IRC channel on freenode, it's not rare to meet people who don't speak English and so are unable to read the Python official documentation. Python wants to be widely available to all users in any language: this is also why Python 3 supports any non-ASCII identifiers: https://www.python.org/dev/peps/pep-3131/#rationale

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

  • There are at least 4 groups of people who are translating the Python documentation to their native language (French [16] [17] [18], Japanese [19] [20], Spanish [21], Hungarian [27] [28]) even though their translations are not visible on d.p.o. Other, less visible and less organized groups, are also translating the documentation, we've heard of Russian [26], Chinese and Korean. Others we haven't found yet might also exist. This PEP defines rules describing how to move translations on docs.python.org so they can easily be found by developers, newcomers and potential translators.

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

  • The Japanese team has (as of March 2017) translated ~80% of the documentation, the French team ~20%. French translation went from 6% to 23% in 2016 [13] with 7 contributors [14], proving a translation team can be faster than the rate the documentation mutates.

    日本团队已经翻译了约80%的文件(截至2017年3月),法国队~20%。 2016年法语翻译从6%上升到23%[13],有7位贡献者[14],证明翻译团队的速度可能比文档变异的速度快。

  • Quoting Xiang Zhang about Chinese translations:

    引用Xiang Zhang在中文翻译中遇到的情况:

  • I have seen several groups trying to translate part of our official doc. But their efforts are disperse and quickly become lost because they are not organized to work towards a single common result and their results are hold anywhere on the Web and hard to find. An official one could help ease the pain.

    我见过几个小组试图翻译部分官方文件。但他们是分散的并且成果很快就会丢失,因为他们没有组织起来为单一的共同结果而努力,最后他们的结果在网上的任何地方都很难找到。一个官方团队可以帮助减轻这种痛苦。

  • Rationale

    基本规则

  • Translation

    翻译

  • Issue tracker

    问题跟踪

  • Considering that issues opened about translations may be written in the translation language, which can be considered noise but at least is inconsistent, issues should be placed outside bugs.python.org (b.p.o).

    考虑到翻译问题会用其母语表述,这些问题应该被认定为噪音,至少是偏离讨论主题的,这些问题应该放在bugs.python.org(b.p.o)之外。

  • As all translation must have their own GitHub project (see Repository for Po Files), they must use the associated GitHub issue tracker.

    由于所有翻译团队都会有自己的GitHub项目(请参阅Po文件库),团队必须使用他们自己GitHub项目的问题跟踪器。

  • Considering the noise induced by translation issues redacted in any languages which may beyond every warnings land in b.p.o, triage will have to be done. Considering that translations already exist and are not actually a source of noise in b.p.o, an unmanageable amount of work is not to be expected. Considering that Xiang Zhang and Victor Stinner are already triaging, and Julien Palard is willing to help on this task, noise on b.p.o is not to be expected.

    考虑由于语言问题b.p.o对这种噪音的警告不是每个译者都能知晓,所以问题分类的工作也必须进行.考虑到翻译已经开始并且实际上不是b.p.o中的噪音源,所以不会出现不可预期的工作量,而且考虑到Xiang Zhang 和Victor Stinner已经在进行分类,而且Julien Palard愿意帮助他们,噪音将会是小概率事件

  • Also, language team coordinators (see Language Team) should help with triaging b.p.o by properly indicating, in the language of the issue author if required, the right issue tracker.

    此外,语言团队协调员(请参阅语言团队)应通过以问题作者的语言(如果需要)正确指出正确的问题跟踪器来帮助对b.p.o进行分类。

  • Branches

    分支

  • Translation teams should focus on last stable versions, and use tools (scripts, translation memory, …) to automatically translate what is done in one branch to other branches.

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

  • Note

    注意

  • Translation memories are a kind of database of previously translated paragraphs, even removed ones. See also Sphinx Internationalization.

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

  • The three currently stable branches that will be translated are [12]: 2.7, 3.5, and 3.6. The scripts to build the documentation of older branches needs to be modified to support translation [12], whereas these branches now only accept security-only fixes.

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

  • The development branch (master) should have a lower translation priority than stable branches. But docsbuild-scripts should build it anyway so it is possible for a team to work on it to be ready for the next release.

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

  • Hosting

    托管

  • Domain Name, Content negotiation and URL

    域名,Content negotiation和URL

  • Different translations can be identified by changing one of the following: Country Code Top Level Domain (CCTLD), path segment, subdomain or content negotiation.

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

  • Buying a CCTLD for each translations is expensive, time-consuming, and sometimes almost impossible when already registered, this solution should be avoided.

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

  • Using subdomains like "es.docs.python.org" or "docs.es.python.org" is possible but confusing ("is it es.docs.python.org or docs.es.python.org?"). Hyphens in subdomains like pt-br.doc.python.org is uncommon and SEOMoz [23] correlated the presence of hyphens as a negative factor. Usage of underscores in subdomain is prohibited by the RFC1123 [24], section 2.1. Finally, using subdomains means creating TLS certificates for each language. This not only requires more maintenance but will also cause issues in language switcher if, as for version switcher, we want a preflight to check if the translation exists in the given version: preflight will probably be blocked by same-origin-policy. Wildcard TLS certificates are very expensive.

    像“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证书非常昂贵。

  • Using content negotiation (HTTP headers Accept-Language in the request and Vary: Accept-Language) leads to a bad user experience where they can't easily change the language. According to Mozilla: "This header is a hint to be used when the server has no way of determining the language via another way, like a specific URL, that is controlled by an explicit user decision." [25]. As we want to be able to easily change the language, we should not use the content negotiation as a main language determination, so we need something else.

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

  • Last solution is to use the URL path, which looks readable, allows for an easy switch from a language to another, and nicely accepts hyphens. Typically something like: "docs.python.org/de/" or, by using a hyphen: "docs.python.org/pt-BR/".

    最后的解决方案是使用直观的URL路径,允许从一种语言轻松切换到另一种语言,并且很好地接受连字符。通常类似于:“docs.python.org/de/”或使用连字符:“docs.python.org/pt-BR/”。

  • As for the version, sphinx-doc does not support compiling for multiple languages, so we'll have full builds rooted under a path, exactly like we're already doing with versions.

    至于版本,sphinx-doc不支持编译多种语言,因此我们将根据路径生成完整版本,就像我们已经在使用版本一样。

  • So we can have "docs.python.org/de/3.6/" or "docs.python.org/3.6/de/". A question that arises is: "Does the language contain multiple versions or does the version contain multiple languages?". As versions exist in any case and translations for a given version may or may not exist, we may prefer "docs.python.org/3.6/de/", but doing so scatters languages everywhere. Having "/de/3.6/" is clearer, meaning: "everything under /de/ is written in German". Having the version at the end is also a habit taken by readers of the documentation: they like to easily change the version by changing the end of the path.

    我们可以选择的是“docs.python.org/de/3.6/”或“docs.python.org/3.6/de/”。问题来了:“语言是包含多个版本还是版本包含多种语言?”。由于版本在任何情况下都存在,并且给定版本的翻译可能存在也可能不存在,我们可能更喜欢“docs.python.org/3.6/de/”,但这样做语言会被分散。 “/de/3.6/”更清晰,意思是:“/ de /下的所有东西都用德语写成”。最终版本依据文档读者的习惯:他们喜欢通过改变路径的末尾来轻松更改版本。

  • So we should use the following pattern: "docs.python.org/LANGUAGE_TAG/VERSION/".

    所以我们应该使用以下模式:“docs.python.org/LANGUAGE_TAG/VERSION/”。

  • The current documentation is not moved to "/en/", instead "docs.python.org/en/" will redirect to "docs.python.org".

    当前文档不存在路径“/ en /”,“docs.python.org/en/”将会重定向到“docs.python.org”。

  • Language Tag

    语言标签

  • A common notation for language tags is the IETF Language Tag [3] [4] based on ISO 639, although gettext uses ISO 639 tags with underscores (ex: pt_BR) instead of dashes to join tags [5] (ex: pt-BR). Examples of IETF Language Tags: fr (French), ja (Japanese), pt-BR (Orthographic formulation of 1943 - Official in Brazil).

    语言标签是基于ISO 639的IETF语言标签[3] [4],尽管gettext使用带下划线的ISO 639标签(例如:pt_BR)而不是破折号[5](例如:pt-BR) )。 IETF语言标签的示例:fr(法语),ja(日语),pt-BR(1943年的正交公式 - 巴西官方)。

  • It is more common to see dashes instead of underscores in URLs [6], so we should use IETF language tags, even if sphinx uses gettext internally: URLs are not meant to leak the underlying implementation.

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

  • It's uncommon to see capitalized letters in URLs, and docs.python.org doesn't use any, so it may hurt readability by attracting the eye on it, like in: "https://docs.python.org/pt-BR/3.6/library/stdtypes.html". RFC 5646 (Tags for Identifying Languages (IETF)) section-2.1 [7] states that tags are not case sensitive. As the RFC allows lower case, and it enhances readability, we should use lowercased tags like pt-br.

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

  • We may drop the region subtag when it does does not add distinguishing information, for example: "de-DE" or "fr-FR". (Although it might make sense, respectively meaning "German as spoken in Germany" and "French as spoken in France"). But when the region subtag actually adds information, for example "pt-BR" for "Portuguese as spoken in Brazil", it should be kept.

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

  • So we should use IETF language tags, lowercased, like /fr/, /pt-br/, /de/ and so on.

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

  • Fetching And Building Translations

    获取和建立翻译

  • Currently docsbuild-scripts are building the documentation [8]. These scripts should be modified to fetch and build translations.

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

  • Building new translations is like building new versions so, while we're adding complexity it is not that much.

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

  • Two steps should be configurable distinctively: Building a new language, and adding it to the language switcher. This allows a transition step between "we accepted the language" and "it is translated enough to be made public". During this step, translators can review their modifications on d.p.o without having to build the documentation locally.

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

  • From the translation repositories, only the .po files should be opened by the docsbuild-script to keep the attack surface and probable bug sources at a minimum. This means no translation can patch sphinx to advertise their translation tool. (This specific feature should be handled by sphinx anyway [9]).

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

  • Community

    社区

  • Mailing List

    邮件列表

  • The doc-sig [30] mailing list will be used to discuss cross-language changes on translated documentation.

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

  • There is also the i18n-sig list but it's more oriented towards i18n APIs [1] than translating the Python documentation.

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

  • Chat

    -

  • Due to the Python community being highly active on IRC, we should create a new IRC channel on freenode, typically #python-doc for consistency with the mailing list name.

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

  • Each language coordinator can organize their own team, even by choosing another chat system if the local usage asks for it. As local teams will write in their native languages, we don't want each team in a single channel. It's also natural for the local teams to reuse their local channels like "#python-fr" for French translators.

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

  • Repository for PO Files

    PO文件Repository

  • Considering that each translation team may want to use different translation tools, and that those tools should easily be synchronized with git, all translations should expose their .po files via a git repository.

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

  • Considering that each translation will be exposed via git repositories, and that Python has migrated to GitHub, translations will be hosted on GitHub.

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

  • For consistency and discoverability, all translations should be in the same GitHub organization and named according to a common pattern.

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

  • Given that we want translations to be official, and that Python already has a GitHub organization, translations should be hosted as projects of the Python GitHub organization [31].

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

  • For consistency, translation repositories should be called python-docs-LANGUAGE_TAG [22], using the language tag used in paths: without region subtag if redundant, and lowercased.

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

  • The docsbuild-scripts may enforce this rule by refusing to fetch outside of the Python organization or a wrongly named repository.

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

  • The CLA bot may be used on the translation repositories, but with a limited effect as local coordinators may synchronize themselves with translations from an external tool, like transifex, and lose track of who translated what in the process.

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

  • Versions can be hosted on different repositories, different directories or different branches. Storing them on different repositories will probably pollute the Python GitHub organization. As it is typical and natural to use branches to separate versions, branches should be used to do so.

    版本托管的形式可以选择在不同的 repositories,不同的目录或不同的分支上。将它们存储在不同的 repositories中可能会污染Python GitHub组织。而使用分支来分离版本是典型和自然的,因此应该使用分支来实现。

  • Translation tools

    翻译工具

  • Most of the translation work is actually done on Transifex [15].

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

  • Other tools may be used later like https://pontoon.mozilla.org/ and http://zanata.org/.

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

  • Documentation Contribution Agreement

    文件贡献协议

  • Documentation does require a license from the translator, as it involves creativity in the expression of the ideas.

    文档确实需要翻译人员的许可,因为它涉及创意表达思想。

  • There's multiple solutions, quoting Van Lindberg from the PSF asked about the subject:

    有多种解决方案,引用PSF的Van Lindberg询问了这个主题:

  • Docs should either have the copyright​ assigned or be under CCO. A permissive software license (like Apache or MIT) would also get the job done, although it is not quite fit for task.

    文档应具有指定的版权或受CCO约束。许可软件许可证(如Apache或MIT)也可以完成工作,尽管它不适合任务。

  • The translators should either sign an agreement or submit a declaration of the license with the translation.

    翻译人员应签署协议或向翻译提交许可声明。

  • We should have in the project page an invitation for people to contribute under a defined license, with acceptance defined by their act of contribution. Such as:

    我们应该在项目页面中邀请人们​​根据明确的许可做出贡献,并通过他们的贡献行为来确定接受。如:

  • "By posting this project on Transifex and inviting you to participate, we are proposing an agreement that you will provide your translation for the PSF's use under the CC0 license. In return, you may noted that you were the translator for the portion you translate. You signify acceptance of this agreement by submitting your work to the PSF for inclusion in the documentation."

    “通过在Transifex上发布此项目并邀请您参与,我们建议您提供一份协议,您将根据CC0许可证提供PSF使用的翻译。作为回报,您可能会注意到您是翻译部分的翻译。您通过将您的工作提交给PSF以包含在文档中来表示接受本协议。“

  • It looks like having a "Documentation Contribution Agreement" is the most simple thing we can do as we can use multiple ways (GitHub bots, invitation page, …) in different context to ensure contributors are agreeing with it.

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

  • Language Team

    语言团队

  • Each language team should have one coordinator responsible for:

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

  • Managing the team.

    管理团队。

  • Choosing and managing the tools the team will use (chat, mailing list, …).

    选择和管理团队将使用的工具(聊天,邮件列表,......)。

  • Ensure contributors understand and agree with the documentation contribution agreement.

    确保贡献者理解并同意文档贡献协议。

  • Ensure quality (grammar, vocabulary, consistency, filtering spam, ads, …).

    确保质量(语法,词汇,一致性,过滤垃圾邮件,广告......)。

  • Redirect issues posted on b.p.o to the correct GitHub issue tracker for the language.

    将b.p.o上发布的问题重定向到该语言的正确GitHub问题跟踪器。

  • Alternatives

    其他方案

  • Simplified English

    简化英文

  • It would be possible to introduce a "simplified English" version like wikipedia did [10], as discussed on python-dev [11], targeting English learners and children.

    有可能引入像维基百科那样的“简化英语”版本[10],如python-dev [11]所述,以方便英语学习者和儿童。

  • Pros: It yields a single translation, theoretically readable by everyone and reviewable by current maintainers.

  • Cons: Subtle details may be lost, and translators from English to English may be hard to find as stated by Wikipedia:

    缺点:微妙的细节可能会丢失,并且这种方式在维基百科也很难找到:

  • > The main English Wikipedia has 5 million articles, written by nearly 140K active users; the Swedish Wikipedia is almost as big, 3M articles from only 3K active users; but the Simple English Wikipedia has just 123K articles and 871 active users. That's fewer articles than Esperanto!

    >主要的英语维基百科有500万篇文章,由近14万活跃用户撰写;瑞典维基百科几乎同样大,300万文章仅来自3千活跃用户;但简单英语维基百科只有12.3万篇文章和871个活跃用户。比世界语还少!

  • Changes

    修订

  • Get a Documentation Contribution Agreement

  • The Documentation Contribution Agreement have to be written by the PSF, then listed at https://www.python.org/psf/contrib/ and have its own page like https://www.python.org/psf/contrib/doc-contrib-form/.

  • Migrate GitHub Repositories

    迁移GitHub仓库

  • We (authors of this PEP) already own French and Japanese Git repositories, so moving them to the Python documentation organization will not be a problem. We'll however be following the New Translation Procedure.

  • Setup a GitHub bot for Documentation Contribution Agreement

  • To help ensuring contributors from GitHub have signed the Documentation Contribution Agreement, We can setup the "The Knights Who Say Ni" GitHub bot customized for this agreement on the migrated repositories [29].

  • Patch docsbuild-scripts to Compile Translations

  • Docsbuild-script must be patched to:

  • List the language tags to build along with the branches to build.

  • List the language tags to display in the language switcher.

  • Find translation repositories by formatting github.com:python/python-docs-{language_tag}.git (See Repository for Po Files)

  • Build translations for each branch and each language.

  • Patched docsbuild-scripts must only open .po files from translation repositories.

  • List coordinators in the devguide

  • Add a page or a section with an empty list of coordinators to the devguide, each new coordinator will be added to this list.

  • Create sphinx-doc Language Switcher

    创建sphinx-doc语言切换器

  • Highly similar to the version switcher, a language switcher must be implemented. This language switcher must be configurable to hide or show a given language.

  • The language switcher will only have to update or add the language segment to the path like the current version switcher does. Unlike the version switcher, no preflight are required as destination page always exists (translations does not add or remove pages). Untranslated (but existing) pages still exists, they should however be rendered as so, see Enhance Rendering of Untranslated and Fuzzy Translations.

  • Update sphinx-doc Version Switcher

  • The patch_url function of the version switcher in version_switch.js have to be updated to understand and allow the presence of the language segment in the path.

  • Enhance Rendering of Untranslated and Fuzzy Translations

  • It's an opened sphinx issue [9], but we'll need it so we'll have to work on it. Translated, fuzzy, and untranslated paragraphs should be differentiated. (Fuzzy paragraphs have to warn the reader what he's reading may be out of date.)

  • New Translation Procedure

  • Designate a Coordinator

  • The first step is to designate a coordinator, see Language Team, The coordinator must sign the CLA.

  • The coordinator should be added to the list of translation coordinators on the devguide.

  • Create Github Repository

  • Create a repository named "python-docs-{LANGUAGE_TAG}" (IETF language tag, without redundent region subtag, with a dash, and lowercased.) on the Python GitHub organization (See Repository For Po Files.), and grant the language coordinator push rights to this repository.

  • Setup the Documentation Contribution Agreement

  • The README file should clearly show the following Documentation Contribution Agreement:

  • 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.

  • Add support for translations in docsbuild-scripts

  • As soon as the translation hits its first commits, update the docsbuild-scripts configuration to build the translation (but not displaying it in the language switcher).

  • Add Translation to the Language Switcher

    添加语种到官方文档语言选择中

  • As soon as the translation hits:

    一旦翻译完成:

  • 100% of bugs.html with proper links to the language repository issue tracker.

    100%的bugs.html与该语言的问题跟踪器的正确链接。

  • 100% of tutorial.

    100%的教程。

  • 100% of library/functions (builtins).

    -

  • the translation can be added to the language switcher.

    这样的翻译可以添加到官方文档语言选择里。

  • 最后,请帮忙写一下简介

来自专栏:每日一译