Sphinx 国际化#

下面讨论 Sphinx 项目文档翻译为多语言的方法。

本文以 sphinx-doc/sphinx-intl 转换为中英双语文档为例来说明实际的操作方法。

研究需要翻译的项目#

研究需要翻译的项目的文档生成方法。

git checkout -b develop

  • 需要配置 Sphinx 环境，即使用 PyPI 安装如下包：

sphinx
sphinx-rtd-theme
sphinx-intl
sphinxcontrib-websupport

  • 进入文档目录，并生成 .po 文件：

cd doc
sphinx-build -b gettext ./ _build/gettext
sphinx-intl update -p _build/gettext -l zh_CN

  • 翻译 .po 为目标语言（即你翻译后的语言），比如（这里被存放在 locale/ 文件夹下）：

#: ../../basic.rst:3
msgid "Basic"
msgstr ""

只需要将 msgid 的值翻译为 msgstr 的值，如 zh_CN 的 基础，即：

#: ../../basic.rst:3
msgid "Basic"
msgstr "基础"

  • 待翻译结束（由你决定），便需要将 .po 编译为 .mo 文件（其中 zh-CN 是目标语言的代号），同时输出最终的文档：

sphinx-build -D language=zh_CN -b html ./ _build/html/zh-CN

如若要保留英语原文，可以使用如下命令：

sphinx-build -D language=en -b html ./ _build/html

这样，/docs/_build/html 目录下存储了中英两个版本的内容。

完善翻译#

我在 GitHub 创建了一个组织 sphinx-locales。目的是为了提高翻译效率，可以将 locale/ 文件夹上传，与他人协助翻译。

再回到项目 daobook/sphinx-intl，把 locale/ 放置在 sphinx-locales/sphinx-intl，并使用 GitHub Action 令上述的翻译过程自动化。

首先，创建文件 requirements.txt，用于配置该项目的 Sphinx 环境。

git clone git@github.com:sphinx-locales/sphinx-intl.git sphinx-intl-locale
cd sphinx-intl-locale

然后，将 daobook/sphinx-intl 生成的 locale/ 复制到 sphinx-intl-locale/ 目录下，并改名为 locales/。

接着，创建文件 .github/workflows/deploy.yml 用于部署自动化流程。

daobook/sphinx-intl deploy.yml#
 1name: deploy
 2on:
 3push:
 4    branches:
 5    - main
 6
 7jobs:
 8# 这个工作流程包含一个名为 "build" 的 job
 9build:
10    # job 将运行的运行器的类型
11    runs-on: ubuntu-latest
12
13    # steps 将作为工作的一部分而执行的任务序列
14    steps:
15    # 这个动作在 $GITHUB_WORKSPACE 下签出你的版本库，以便工作流就可以访问它
16    - uses: actions/checkout@v2
17    # 设定 Python 环境
18    - name: Set up Python
19        uses: actions/setup-python@v2
20        with:
21        python-version: 3.9
22    # 设定 conda 环境
23    - uses: s-weigand/setup-conda@v1
24    - run: conda --version
25    - run: which python
26
27    # 安装依赖包
28    - name: Install dependencies
29        run: |
30        pip install -r requirements.txt
31
32    # 克隆
33    - name: Clone
34        run: |
35        git clone https://github.com/daobook/sphinx-intl.git draft
36
37    # 构建 Sphinx 文档
38    - name: Build the book
39        run: |
40        cp locales/ -rf draft/doc/locale/
41        cd draft/doc
42        sphinx-build -b gettext ./ _build/gettext
43        sphinx-intl update -p _build/gettext -l zh_CN
44        sphinx-build -D language=en -b html ./ _build/html/
45        sphinx-build -D language=zh_CN -b html ./ _build/html/zh-CN
46        cd ../..
47        cp -rf draft/docs/_build/ _build
48        rm -rf draft/
49
50    # 部署 HTML 到 gh-pages 分支
51    - name: GitHub Pages action
52        uses: peaceiris/actions-gh-pages@v3.6.1
53        with:
54        github_token: ${{ secrets.GITHUB_TOKEN }}
55        publish_dir: _build/html
56        user_name: "github-actions[bot]"
57        user_email: "github-actions[bot]@users.noreply.github.com"

最后，使用 Git 上传，便会自动化部署到 sphinx-intl 预览效果。可以不断的修改，直到你觉得翻译的意思没有问题为止。

注解

对于 Jupyter Book 项目，需要做一些调整：

- name: Build the book
  run: |
    cp locales/ -rf draft/doc/locale/
    cd draft/doc
    jb build --builder custom --custom-builder gettext --path-output _gettext .
    rm -rf _gettext/_build/.jupyter_cache/ _gettext/_build/jupyter_execute 
    sphinx-intl update -p _gettext/_build/gettext -l zh_CN
    jb build .
    ...

重要

高亮的部分是依据您的项目而定的。

更新源文档#

如果 sphinx-doc/sphinx-intl 文档有所改动，相应的 locales/ 则需要更新。基于此，再次回到项目 daobook/sphinx-intl 的 develop 分支下。

首先，sphinx-intl 翻译的 locales/ 覆盖 daobook/sphinx-intl 的 doc/locale：

git clone https://github.com/sphinx-locales/sphinx-intl.git draft/
rm -rf doc/locale
cp -rf draft/locales/ doc/locale/
rm -rf draft

其次，进入文档目录，并生成 .po 文件：

cd doc
sphinx-build -b gettext ./ _build/gettext
sphinx-intl update -p _build/gettext -l zh_CN

最后，校队并翻译 .po 文件。觉得，翻译的差不多了，再次将其 locale/ 文件夹替换掉 sphinx-intl 的 locales/ 文件夹。

贡献源文档#

如若您需要对源文档，即 sphinx-doc/sphinx-intl 的 /docs/ 中的内容做出修改或者添加等贡献行为，则可以这样做。

首先，贡献源文档，并更新 sphinx-intl 的 locales/ 文件夹。 其次，创建 daobook/sphinx-intl 的自动化流程 .github/workflows/deploy.yml：

 1...
 2  # 安装依赖包
 3  - name: Install dependencies
 4    run: |
 5      pip install -r doc/requirements.txt
 6
 7  # 克隆
 8  - name: Clone
 9    run: |
10      git clone https://github.com/sphinx-locales/sphinx-intl.git draft
11
12  # 构建 Sphinx 文档
13  - name: Build the book
14    run: |
15      cp -rf draft/locales/ doc/locale/
16      rm -rf draft/
17      cd doc
18      sphinx-build -b gettext ./ _build/gettext
19      sphinx-intl update -p _build/gettext -l zh_CN
20      sphinx-build -D language=en -b html ./ _build/html/
21      sphinx-build -D language=zh_CN -b html ./ _build/html/zh-CN
22      cd ..
23      cp -rf doc/_build/ _build/
24      rm -rf doc/_build/
25...

其中，... 部分，同 daobook/sphinx-intl deploy.yml。

重要

高亮的部分是依据您的项目而定的。

小技巧#

VSCode 中 po 文件的高亮，可以使用 vscode 插件 gettext。