支持文档翻译#
我们支持并鼓励将 Jupyter 文档翻译成其他语言，以此作为使我们的社区更具包容性和多样性的一种方式。我们正在努力建立一个基于 Python 和 Django 社区先前工作，在 Jupyter 项目中翻译 Sphinx 文档的一致模型。本项目 (https://jupyter-docs.pythonlang.cn) 和 Jupyter Docker Stacks 项目是早期采用者，旨在验证本页描述的工作流程。
概述#
项目初始设置后，Sphinx 文档及其翻译的更改遵循持续集成 (CI) 和持续部署 (CD)，与项目源代码类似。
谁参与文档翻译#
欢迎任何人通过参与下面描述的工作流程来编写和翻译 Jupyter 文档。此工作流程涉及一些参与者和组件
修改英文项目文档的人员
将英文文档中的文本片段翻译成另一种语言（区域设置）的人员
用于源文档语言（例如，美国英语，
en-US）和其他区域设置（例如，巴西葡萄牙语，pt-BR；摩洛哥阿拉伯语，ar-MA）的可移植对象文件 (.po)持续集成系统，如 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 Web 应用程序创建、审阅和更新这些语言的翻译（例如，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 以友好的 Web 界面来培训翻译人员，而无需他们了解 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 组织管理员可以按照以下说明为 GitHub 组织中与 Transifex 上的项目对应的 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 项目
requirements.txt或environment.yaml中尚不存在，请添加sphinx-intl。在
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 actions 工作流程文件
.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 中创建的翻译项目名称。
点击 添加。
对项目支持的所有其他语言重复这些步骤。
现在，每当您合并来自 Transifex 的包含 .po 翻译文件更新的拉取请求时，ReadTheDocs 将构建源文档站点以及所有支持语言的站点。ReadTheDocs 将这些站点相互关联，并通过弹出窗口中的语言链接使其可访问。
参考#
https://github.com/parente/helloworld-transifex-rtd 是一个配置为支持本文档中描述的整个工作流程的迷你项目。