支持文档翻译#
我们支持并鼓励将 Jupyter 文档翻译成其他语言，以此作为让我们的社区更具包容性和多样性的方式之一。我们正在努力为基于 Sphinx 的 Jupyter 项目文档翻译建立一个一致的模型，该模型基于 Python 和 Django 社区先前的工作。此项目 (https://jupyter-docs.pythonlang.cn) 和 Jupyter Docker Stacks 项目 是早期采用者，旨在证明此页面中描述的工作流。
概述#
在进行初始项目设置后，对 Sphinx 文档及其翻译的更改将遵循持续集成 (CI) 和持续部署 (CD)，就像项目源代码一样。
谁参与翻译文档#
欢迎任何人通过参与以下描述的工作流来参与编写和翻译 Jupyter 文档。此工作流有少数参与者和组件
对英语项目文档进行更改的人
将英语文档中的文本片段翻译成另一种语言（语言环境）的人
可移植对象文件 (
.po)，用于源文档语言（例如，美式英语，en-US）和其他语言环境（例如，巴西葡萄牙语，pt-BR；摩洛哥阿拉伯语，ar-MA）负责以下工作的持续集成系统，例如 TravisCI、CircleCI 或 GitHub Actions
ReadTheDocs，我们首选的构建和托管文档服务
Transifex，一个针对开源项目提供免费计划的本地化平台，具有友好的 Web 界面，并支持
.po文件
翻译流程#
用户创建或编辑用美式英语编写的 reStructuredText (
.rst) 或 Markdown (.md) 文档。用户在 GitHub 上提交一个拉取请求。
项目维护人员审查并合并拉取请求。
ReadTheDocs 运行 Sphinx 将美式英语源文档转换为 HTML（例如，https://jupyter-docs.pythonlang.cn/en/latest/architecture/how_jupyter_ipython_work.html）
与此同时，CI 服务运行 Sphinx 命令，从美式英语文档中提取可翻译的消息，并将其放入
en-US可移植对象 (.po) 文件中。例如
# 5164fcd91a8a4700ac734562245773ad
#: ../../source/architecture/how_jupyter_ipython_work.rst:13
#: f68a21b0bc884dad9021c276e6490e6d
msgid ""
"The IPython kernel that provides computation and communication with the "
"frontend interfaces, like the notebook"
msgstr ""
CI 服务将英语
.po文件提交到 GitHub 上的项目中。（例如，https://github.com/jupyter/jupyter/commit/1330bc409842d8b8a7bbb3a1c63259c34a543be0）Transifex 使英语
.po文件中的消息可以翻译成所有配置的语言。随着时间的推移，翻译团队使用 Transifex 网络应用程序为这些语言创建、审查和更新翻译（例如，https://docs.transifex.com/translation/translating-with-the-web-editor）
当所有英语消息都已翻译（并且可选地审查）为特定语言时，Transifex 会向 GitHub 项目提交一个包含本地化
.po文件的拉取请求（例如，https://github.com/jupyter/jupyter/pull/485）。例如
# 5164fcd91a8a4700ac734562245773ad
#: ../../source/architecture/how_jupyter_ipython_work.rst:13
msgid ""
"The IPython kernel that provides computation and communication with the "
"frontend interfaces, like the notebook"
msgstr ""
"The IPython kernel que fornece o cálculo e a comunicação com as interfaces "
"de frontend como o notebook"
项目维护人员审查并合并拉取请求。
ReadTheDocs 再次运行 Sphinx 将美式英语源文档转换为 HTML。
ReadTheDocs 还运行 Sphinx 加载本地化
.po文件，将翻译替换到原始英语文本中，并将这些翻译后的文档转换为 HTML（例如，https://jupyter-docs.pythonlang.cn/pt_BR/latest/architecture/how_jupyter_ipython_work.html）
注意：我们认识到此流程假定文档最初是用美式英语编写的。如果这成为新贡献的重大障碍，我们应该考虑在未来取消此假设。
社区翻译人员工作流程#
当 Jupyter 社区成员希望帮助翻译文档时，我们感到非常高兴。我们使用 Transifex 在友好的网络界面中接纳翻译人员，而无需了解 git、GitHub、Sphinx 或其他软件开发人员工具。
创建翻译#
翻译人员入门 是一个出色的指南，供新的 Transifex 用户使用。按照说明创建帐户。当提示加入团队时，查找jupyter-meta-documentation，开始为本文档站点贡献翻译。或者，在创建帐户后访问 https://www.transifex.com/project-jupyter/jupyter-meta-documentation/，并请求加入项目。项目维护人员或语言团队协调员将审查并批准您的请求。
审查翻译#
Transifex 支持 审查翻译，由语言团队成员进行同行审查，以确保翻译质量。项目维护人员可以选择 Transifex 是否应该在文档中的所有文本翻译可用时立即发送拉取请求，或者在所有这些翻译都经过审查后才延迟提交拉取请求（此项目的当前设置）。
协调翻译团队#
项目维护者还可以授予 Transifex 团队成员语言协调员的角色。语言协调员有权邀请用户加入语言团队、批准或拒绝加入请求、分配语言团队角色，以及为特定项目语言执行其他管理操作。授权社区中值得信赖的成员担任协调员，可以在不涉及软件开发人员的情况下帮助翻译团队壮大。
管理员工作流#
上面描述的翻译 CI/CD 工作流需要在 GitHub 和 Transifex 中进行配置才能正常运行。项目维护者可以按照以下说明为其 Sphinx 文档启用翻译。
创建 Transifex 组织#
Transifex 在组织下组织翻译项目，这些组织镜像 GitHub 上的组织和存储库。目前，只有 https://github.com/jupyter 组织在 Transifex 上有对应的组织 (https://www.transifex.com/project-jupyter/public/)，其中有以下组织管理员
@choldgraf
@parente
@willingc
具有在 GitHub 组织中安装应用程序权限的 GitHub 用户可以按照这些说明创建新的 Transifex-GitHub 组织链接（例如，对于 https://github.com/jupyterhub、https://github.com/jupyterlab）。
在 https://transifex.com 创建一个新用户帐户。
完成注册向导。
创建并命名一个新组织。
单击 Transifex 仪表板页面右上角的组织下拉菜单，然后选择组织设置。
单击左侧边栏中的详细信息。
单击管理部分中的邀请管理员，将其他管理员添加到 Transifex 组织。
单击左侧边栏中的管理集成。
单击 GitHub 部分中的安装 Transifex 应用程序。
选择要与新 Transifex 组织关联的 GitHub 组织。
选择 Transifex 有权访问的存储库。
返回到单击安装 Transifex 应用程序的选项卡，然后单击 GitHub 部分中的授权 Transifex。
在弹出对话框中选择你刚配置的 GitHub 组织。
请注意，你可以随时访问 https://github.com/settings/installations 来修改 GitHub-Transifex 集成。
创建 Transifex 项目#
Transifex 组织管理员可以按照以下说明为与 Transifex 上的组织对应的 GitHub 组织中的 GitHub 项目配置新的翻译项目。
访问 https://www.transifex.com。
使用组织的相应管理员用户帐户登录。
单击 Transifex 仪表板页面右上角的组织下拉菜单，然后选择组织设置。
单击左下侧边栏中的创建新项目。
根据 GitHub 上的项目命名翻译项目。
选择公开作为隐私类型，表明该项目是开源的，并提供存储库的 GitHub URL。
选择基于文件的项目。
为项目创建一个新团队。
选择英语 (en)作为源语言。
选择已知的目标语言。（你也可以稍后添加这些语言。）
单击创建项目。
单击左侧边栏中项目名称下的设置。
单击维护者选项卡。
邀请其他项目维护者，通常是负责维护持续集成和引导语言团队的软件开发人员。
配置语言和团队#
Transifex 组织管理员和项目经理可以向项目添加翻译语言。
访问 https://www.transifex.com。
使用组织的相应管理员用户帐户登录。
单击左侧边栏中项目名称下的语言。
单击编辑语言。
添加或移除目标翻译语言。
点击应用。
组织管理员、项目维护者和团队经理可以向翻译团队中添加用户，并赋予其语言协调员、审阅者或翻译者的角色。
点击顶部导航栏中的团队。
点击右上角的邀请协作者按钮。
输入要添加到项目中的人的用户名、电子邮件地址或全名。请注意，此字段中的自动完成并不总是为要邀请的用户显示弹出窗口。确认您输入了正确的值，然后继续。
选择角色分配给用户。
如果角色适用于特定团队，请选择该团队。
如果角色适用于特定语言，请选择该语言。
点击邀请更多以输入其他用户或发送邀请。
配置 Transifex-GitHub 集成#
在 Transifex 上配置组织和项目资源后，项目开发人员可以
配置 Sphinx 以生成源语言的
.po文件并读取包含翻译的.po文件配置 Transifex 以监视源语言
.po文件更改配置项目 CI 服务以在贡献者对源文档进行更改时更新源语言
.po文件
本节中的说明假定 git 存储库已在以下目录结构中包含 Sphinx 文档
my-project/
docs/
build/ # built sphinx artifacts go here
source/ # documentation source is in here
conf.py # sphinx config file
index.rst # root of the documentation
requirements.txt # sphinx, sphinx-intl, etc.
项目开发人员可以执行以下操作来配置 Sphinx 以播种源 .po 文件和识别翻译 .po 文件。
如果尚未存在，请将
sphinx-intl添加到 Sphinx 项目requirements.txt或environment.yaml。在
docs/目录中运行sphinx-intl create-txconfig。将以下内容添加到 Sphinx
source/conf.py文件中。
# -- Translation -------------------------------------------------------------
gettext_uuid = True
locale_dirs = ["locale/"]
运行
make gettext以从英文源文档中提取所有字符串。运行
sphinx-intl update -l en以生成英文源.po文件。提交、审阅并合并包含更改和生成的
.po文件的拉取请求。
合并拉取请求后，将 Transifex 项目链接到 GitHub 存储库。
访问 https://www.transifex.com。
单击左侧边栏中项目名称下的设置。
点击集成选项卡。
在 GitHub 部分中点击链接存储库。
选择适当的 GitHub 存储库和集成分支。然后点击下一步。
将以下配置复制并粘贴到对话框中，根据需要调整注释值，然后单击下一步。
filters:
- filter_type: dir
file_format: PO
source_file_extension: po
# Change this if you selected a different source language during project setup
source_language: en
# The path in the GitHub repository where the source .po files reside
source_file_dir: "docs/source/locale/en/LC_MESSAGES"
# The path in the GitHub repository where translation .po files reside
translation_files_expression: "docs/source/locale/<lang>/LC_MESSAGES"
选择 Transifex 将何时将翻译提交回存储库。然后单击保存和同步。
单击关闭。
查看同步状态进度。
单击左侧边栏中的资源。
单击其中一个
.po文件，查看按语言划分的翻译进度。单击其中一种语言，查看有关翻译进度、翻译文本和审阅翻译的详细信息。有关详细信息，请参阅上面的翻译人员工作流部分。
在确认初始英文 .po 文件已到达 Transifex 后，设置持续集成以确保每当英文文档更改时，Transifex 中的源字符串都保持最新。完成此操作的步骤因 CI 提供商而异。以下说明在使用 GitHub Actions 时该怎么做。
在项目中创建新的 GitHub 操作工作流文件
.github/workflows/gettext.yml。将以下内容添加到文件中。请注意，
secrets.GITHUB_TOKEN是内置机密，无需提前配置。
name: Extract Translatable Strings
# Run on all branch pushes
on:
push:
paths:
- "docs/source/**"
- "!docs/source/locale/**"
- ".github/workflows/gettext.yml"
jobs:
gettext:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@master
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: "3.x"
- name: Install dependencies
working-directory: docs
run: pip install -r requirements.txt
- name: Extract source strings
working-directory: docs
run: |
make gettext
sphinx-intl update -l en
- name: Push to master
# Only commit changes to master if master just changed
if: github.ref == 'refs/heads/master'
uses: mikeal/publish-to-github-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
提交、审阅并合并包含工作流 YAML 的拉取请求。
完成本节中的步骤后，主分支上源英文文档的任何更改都会被拉入 Transifex 以进行翻译。同样，在 Transifex 上完成的任何翻译都会作为拉取请求提交回 GitHub 上的项目。
在 ReadTheDocs 上托管翻译#
ReadTheDocs 支持从单个 GitHub 项目及其翻译构建 HTML 文档站点。ReadTheDocs 上源语言文档项目的管理员可以按照以下说明为其他语言启用构建。
访问 https://readthedocs.org/dashboard/
记下包含源语言的现有 ReadTheDocs 项目的名称（例如，
jupyter）。单击
导入 一个 项目。单击
手动 导入。输入上面记下的项目名称，后缀为目标语言区域设置（例如，
jupyter-es、jupyter-pt-br）。输入项目的 GitHub URL。
选中编辑高级项目选项。
单击下一步。
从语言下拉菜单中选择目标语言的名称（例如，
es-> 西班牙语、es-mx-> 墨西哥西班牙语、pt-br-> 巴西葡萄牙语）。单击
完成。返回 https://readthedocs.org/dashboard/ 上的项目列表
单击包含源语言的项目。
单击管理。
单击翻译。
从项目下拉菜单中选择在步骤 5 中创建的翻译项目名称。
单击添加。
对项目支持的所有其他语言重复这些步骤。
现在，每当您合并包含 .po 翻译文件更新的来自 Transifex 的拉取请求时，ReadTheDocs 都会构建源文档站点以及所有受支持语言的站点。ReadTheDocs 会将这些站点相互关联，并通过弹出窗口中的语言链接使它们可访问。
参考#
https://github.com/parente/helloworld-transifex-rtd 是一个小型项目，配置为支持本文档中描述的整个工作流。