支持文档的翻译#

我们支持和鼓励将 Jupyter 文档翻译成其他语言，以此作为使我们的社区更加包容和多样化的方式之一。我们正在努力为 Jupyter 项目中的 Sphinx 文档翻译建立一个一致的模型，这一模型基于 Python 和 Django 社区的先前工作。这个项目（https://jupyter.readthedocs.io）和 Jupyter Docker Stacks 项目 是早期采用者，旨在验证本页描述的工作流程。

概述#

在初始项目设置之后，Sphinx 文档及其翻译的更改遵循持续集成 (CI) 和持续部署 (CD) 流程，这与项目源代码非常相似。

谁参与了文档翻译#

欢迎任何人通过参与以下描述的工作流程来参与编写和翻译 Jupyter 文档。此工作流程涉及一些角色和组件：

  • 对英语项目文档进行修改的人

  • 将英文文档中的文本片段翻译成另一种语言（本地化）的人

  • 便携对象文件（.po） 用于源文档语言（例如，美国英语，en-US）和其他地区（例如，巴西葡萄牙语，pt-BR；摩洛哥阿拉伯语，ar-MA）

  • 像 TravisCI、CircleCI 或 GitHub Actions 这样的持续集成系统，负责

  • ReadTheDocs，我们首选的文档构建和托管服务

  • Transifex 是一个本地化平台，为开源项目提供免费计划，拥有友好的网页界面，并支持 .po 文件。

翻译过程#

  1. 用户创建或编辑用美式英语编写的 reStructuredText (.rst) 或 Markdown (.md) 文档。

  2. 用户在 GitHub 上提交了一个拉取请求。

  3. 项目维护者审查并合并拉取请求。

  4. ReadTheDocs 使用 Sphinx 将美国英语源文档转换为 HTML（例如，https://jupyter.readthedocs.io/en/latest/architecture/how_jupyter_ipython_work.html）

  5. 与此同时，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 ""

  1. CI 服务将英文 .po 文件提交到 GitHub 上的项目中。（例如，https://github.com/jupyter/jupyter/commit/1330bc409842d8b8a7bbb3a1c63259c34a543be0）

  2. Transifex 使得英文 .po 文件中的消息可用于所有配置语言的翻译。

  3. 随着时间的推移，翻译团队使用 Transifex 网络应用程序来创建、审查和更新这些语言的翻译（例如，https://docs.transifex.com/translation/translating-with-the-web-editor）

  4. 当给定语言（例如，https://github.com/jupyter/jupyter/pull/485）的所有英文消息都已翻译，并且可选地经过审核后，Transifex 会向 GitHub 项目提交一个包含本地化 .po 文件的拉取请求。例如：

# 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"

  1. 项目维护者审查并合并拉取请求。

  2. ReadTheDocs 再次运行 Sphinx 将美国英语源文档转换为 HTML。

  3. ReadTheDocs 也运行 Sphinx 来加载本地化的 .po 文件，将翻译替换到原始的英文文本中，并将这些翻译后的文档转换为 HTML（例如，https://jupyter.readthedocs.io/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）。

  1. 在 https://transifex.com 创建一个新用户账户。

  2. 完成注册向导。

  3. 创建并命名一个新组织。

  4. 点击 Transifex 仪表板页面右上角的组织下拉菜单，然后选择 组织设置。

  5. 点击左侧边栏中的 详细信息。

  6. 点击 Management 部分中的 inviting administrators ，以向 Transifex 组织添加额外的管理员。

  7. 点击左侧边栏中的 管理集成 。

  8. 点击 GitHub 部分中的 安装 Transifex 应用。

  9. 选择要与新 Transifex 组织关联的 GitHub 组织。

  10. 选择 Transifex 有权访问的仓库。

  11. 返回到你点击 安装 Transifex 应用 的标签页，然后在 GitHub 部分点击 授权 Transifex。

  12. 在弹出对话框中选择您刚刚配置的GitHub组织。

请注意，您可以随时通过访问 https://github.com/settings/installations 来修改 GitHub-Transifex 集成。

创建一个Transifex项目#

Transifex 组织管理员 可以按照以下说明为 GitHub 组织中对应于 Transifex 上的 GitHub 项目配置新的翻译项目。

  1. 访问 https://www.transifex.com。

  2. 使用组织的适当管理员用户帐户登录。

  3. 点击 Transifex 仪表板页面右上角的组织下拉菜单，然后选择 组织设置。

  4. 点击左下侧边栏中的 创建新项目。

  5. 以GitHub上的项目命名翻译项目。

  6. 选择 Public 作为隐私类型，表明该项目是开源的，并提供仓库的 GitHub URL。

  7. 选择一个基于文件的项目。

  8. 为项目创建一个新团队。

  9. 选择 英语 (en) 作为源语言。

  10. 选择已知的目标语言。（你也可以稍后添加这些。）

  11. 点击 创建项目。

  12. 点击左侧边栏中项目名称下的 设置 。

  13. 点击 维护者 标签。

  14. 邀请额外的 项目维护者，通常是负责维护持续集成和引导语言团队的软件开发者。

配置语言和团队#

Transifex 组织管理员和项目经理可以向项目添加翻译语言。

  1. 访问 https://www.transifex.com。

  2. 使用组织的适当管理员用户帐户登录。

  3. 点击左侧边栏中项目名称下的 语言 。

  4. 点击 编辑语言。

  5. 添加或移除目标翻译语言。

  6. 点击 应用。

组织管理员、项目维护者和 团队经理 可以将用户添加到翻译团队中，角色可以是语言协调员、审阅者或翻译者。

  1. 点击顶部导航栏中的 Teams。

  2. 点击右上角的 邀请协作者 按钮。

  3. 输入要添加到项目中的人员的用户名、电子邮件地址或全名。请注意，此字段中的自动完成功能并不总是会显示您希望邀请的用户的弹出窗口。确认您输入了正确的值并继续。

  4. 选择要分配给用户的角色。

  5. 如果角色适用于特定团队，请选择该团队。

  6. 如果角色适用于特定语言，请选择该语言。

  7. 点击 邀请更多 以输入其他用户或 发送邀请。

配置 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 文件。

  1. 如果 sphinx-intl 尚未存在，请将其添加到您的 Sphinx 项目的 requirements.txt 或 environment.yaml 中。

  2. 在 docs/ 目录中运行 sphinx-intl create-txconfig。

  3. 将以下内容添加到 Sphinx source/conf.py 文件中。

# -- Translation -------------------------------------------------------------

gettext_uuid = True
locale_dirs = ["locale/"]

  1. 运行 make gettext 以从英文源文档中提取所有字符串。

  2. 运行 sphinx-intl update -l en 以生成英文源 .po 文件。

  3. 提交、审查并合并包含更改和生成的 .po 文件的拉取请求。

合并拉取请求后，将 Transifex 项目链接到 GitHub 仓库。

  1. 访问 https://www.transifex.com。

  2. 点击左侧边栏中项目名称下的 设置 。

  3. 点击 集成 标签。

  4. 点击 GitHub 部分的 链接仓库。

  5. 选择适当的 GitHub 仓库和集成分支。然后点击 下一步。

  6. 将以下配置复制并粘贴到对话框中，根据需要调整注释的值，然后点击 下一步。

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"

  1. 选择 Transifex 何时将翻译提交回仓库。然后点击 保存并同步。

  2. 点击 关闭。

  3. 查看同步状态进度。

  4. 点击左侧边栏中的 资源 。

  5. 点击其中一个 .po 文件以查看按语言划分的翻译进度。

  6. 点击以下任一语言以查看翻译进度详情、翻译文本及审核翻译。详情请参阅上方的社区翻译者工作流程部分。

在确认初始的英文 .po 文件已到达 Transifex 后，设置持续集成以确保每当英文文档更改时，Transifex 中的源字符串保持最新。实现这一目标的步骤因 CI 提供商而异。以下描述了在使用 GitHub Actions 时应如何操作。

  1. 在项目中创建一个新的 GitHub Actions 工作流文件 .github/workflows/gettext.yml。

  2. 将以下内容添加到文件中。请注意，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 }}

  1. 提交、审查并合并包含工作流 YAML 的拉取请求。

一旦您完成了本节中的步骤，主分支上源英文文档的任何更改都会被拉取到 Transifex 进行翻译。同样，Transifex 上完成的任何翻译都会作为拉取请求提交回 GitHub 上的项目。

在 ReadTheDocs 上托管翻译#

ReadTheDocs 支持从单个 GitHub 项目及其翻译中构建 HTML 文档站点。ReadTheDocs 上源语言文档项目的管理员可以按照这些说明为其他语言启用构建。

  1. 访问 https://readthedocs.org/dashboard/

  2. 注意包含您源语言的现有 ReadTheDocs 项目的名称（例如，jupyter）。

  3. 点击 导入项目。

  4. 点击 手动导入。

  5. 输入你在上面记录的项目名称，后缀为目标语言区域设置（例如，jupyter-es，jupyter-pt-br）。

  6. 输入项目的 GitHub URL。

  7. 检查 编辑高级项目选项 。

  8. 点击 Next。

  9. 从 Language 下拉菜单中选择目标语言的名称（例如 es -> 西班牙语，es-mx -> 墨西哥西班牙语，pt-br -> 巴西葡萄牙语）。

  10. 点击 完成。

  11. 返回项目列表：https://readthedocs.org/dashboard/

  12. 点击包含源语言的项目。

  13. 点击 Admin。

  14. 点击 Translations。

  15. 从 Project 下拉菜单中选择在第5步创建的翻译项目的名称。

  16. 点击 添加。

  17. 对项目支持的所有其他语言重复这些步骤。

现在，每当你从Transifex合并包含.po翻译文件更新的拉取请求时，ReadTheDocs将构建源文档站点以及所有支持语言的站点。ReadTheDocs会将这些站点相互关联，并通过弹出窗口中的语言链接使它们可访问。

Project Jupyter 文档站点，右侧打开的 ReadTheDocs 弹出窗口显示了其他语言的文档链接。

参考#

https://github.com/parente/helloworld-transifex-rtd 是一个配置为支持本文档中描述的整个工作流程的迷你项目。

On this page
Edit on GitHub
显示源代码