国际化

Added in version 1.1.

与Sphinx生成的消息（如导航栏）提供的翻译互补,Sphinx提供了促进*文档*翻译的机制.有关配置的详细信息,请参见 国际化选项 .

Sphinx中翻译的工作流可视化.（该图由 plantuml 创建.）

Sphinx国际化细节

gettext [1] 是国际化和本地化的一个既定标准.它天真地将程序中的消息映射到翻译后的字符串.Sphinx 使用这些功能来翻译整个文档.

最初,项目维护者需要收集所有可翻译的字符串（也称为 消息）,以便让翻译人员知道它们. Sphinx 通过调用 sphinx-build -M gettext 提取这些字符串.

文档树中的每一个元素都将最终生成一条消息,这导致列表被均等地分割成不同的块,而大型段落将保持与原始文档相同的粗粒度.这使得文档更新无缝进行,同时为翻译者在自由文本段落中提供了一定的上下文.维护者的任务是拆分过大的段落,因为没有合理的自动化方法来做到这一点.

在 Sphinx 成功运行 MessageCatalogBuilder 后,您将在输出目录中找到一组 .pot 文件.这些是 目录模板,仅包含您原始语言的消息.

它们可以被交付给翻译人员,这些翻译人员将其转换为 .po 文件 —— 即所谓的 消息目录 —— 其中包含原始消息与外语字符串之间的映射.

gettext 通过 msgfmt 将它们编译成一种称为 二进制目录 的二进制格式,以提高效率.如果你通过 locale_dirs 使这些文件对你的 language 可发现,Sphinx 将自动识别它们.

示例:您在 Sphinx 项目中有一个文档 usage.rst . gettext 构建器会将其消息放入 usage.pot . 想象一下,您在 usage.po 中存储了西班牙语翻译 [2] — 要使您的构建被翻译,您需要遵循以下说明:

• 将您的消息目录编译到某个语言目录,例如 locale ,以便它最终出现在 :file :./locale/es/LC_MESSAGES/usage.mo 中的源目录（其中 es 是西班牙语的语言代码）.

  msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
  

• 将 locale_dirs 设置为 ["locale/"] .

• 将 language 设置为 es （也可以通过 -D 进行设置）.

• 运行您所需的构建.

为了防止错误,如果翻译段落中的交叉引用与原始内容不匹配,将发出警告.可以通过 suppress_warnings 配置变量全局关闭此警告.或者,要仅针对一条信息关闭它,可以在消息末尾添加 #noqa ,如下所示:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(写 \#noqa 如果您希望在文本中字面上包含 “#noqa”.这不适用于代码块,因为 #noqa 会被忽略,因为代码块中反正不包含引用.)

Added in version 4.5: The #noqa mechanism.

使用 sphinx-intl 进行翻译

快速指南

sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with sphinx-intl.

1. 安装 sphinx-intl .

   $ pip install sphinx-intl
   

2. 将配置添加到 conf.py .

   locale_dirs = ['locale/']   # path is example but recommended.
   gettext_compact = False     # optional.
   

   本案例研究假设 BUILDDIR 设置为 _build ,:confval:locale_dirs 设置为 locale/ ,并且 gettext_compact 设置为 False （Sphinx 文档已经配置为这样）.

3. 提取可翻译的消息到 pot 文件中.

   $ make gettext
   

   生成的 pot 文件将放置在 _build/gettext 目录中.如果您想自定义输出,超出 国际化选项 的功能,可以用放置在 templates_path 中的自定义 message.pot.jinja 文件替换 默认 pot 文件模板 .

4. 生成 po 文件.

   我们将使用上一步生成的 pot 文件.

   $ sphinx-intl update -p _build/gettext -l de -l ja
   

   完成后,生成的 po 文件将放置在以下目录中:

   • ./locale/de/LC_MESSAGES/

   • ./locale/ja/LC_MESSAGES/

5. 翻译 po 文件.

   如上所述,这些位于 ./locale/<lang>/LC_MESSAGES 目录中. 以下是 Sphinx 的一个示例文件:builders.po .

   # a5600c3d2e3d48fc8c261ea0284db79b
   #: ../../builders.rst:4
   msgid "Available builders"
   msgstr "<FILL HERE BY TARGET LANGUAGE>"
   

   另一个案例,msgid 是多行文本并包含 reStructuredText 语法:

   # 302558364e1d41c69b3277277e34b184
   #: ../../builders.rst:9
   msgid ""
   "These are the built-in Sphinx builders. More builders can be added by "
   ":ref:`extensions <extensions>`."
   msgstr ""
   "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
   "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
   

   请小心,不要破坏reStructuredText语法.大多数po编辑器会帮助您做到这一点.

6. 构建翻译的文档.

   你需要在 conf.py 中设置 language 参数,或者也可以在命令行中指定该参数.

   对于BSD/GNU make,运行:

   $ make -e SPHINXOPTS="-D language='de'" html
   

   对于Windows cmd.exe ,运行:

   > set SPHINXOPTS=-D language=de
   > .\make.bat html
   

   对于 PowerShell,请运行:

   PS> Set-Item env:SPHINXOPTS "-D language=de"
   PS> .\make.bat html
   

恭喜!您已在 _build/html 目录中获得翻译后的文档.

Added in version 1.3: sphinx-build 由 make 命令调用,将 po 文件构建为 mo 文件.

如果您使用的是1.2.x或更早版本,請在執行 make 命令之前,先執行 sphinx-intl build 命令.

翻译

通过新的 pot 文件更新您的 po 文件

如果文档被更新,就需要生成更新后的 pot 文件,并将差异应用于翻译后的 po 文件.要将 pot 文件中的更新应用到 po 文件中,请使用 sphinx-intl update 命令.

$ sphinx-intl update -p _build/gettext

使用Transifex服务进行团队翻译

Transifex 是几个允许通过网页界面进行协作翻译的服务之一.它拥有一个方便的基于 Go 的命令行客户端,便于获取和推送翻译.

1. 安装 Transifex CLI 工具 .

   您需要 tx 命令行工具来上传资源 (pot 文件).官方安装过程会将 tx 二进制文件放置在当前目录,并附带一个 README 和一个 LICENSE 文件,并将当前目录添加到 $PATH 中.

   $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
   

   参见

   Transifex Client documentation

2. 创建您的 Transifex 账户,并为您的文档创建一个新项目和一个组织.

   当前,Transifex不允许一个翻译项目拥有多个版本的文档,因此最好在项目名称中包含版本号.

   例如:

   组织 ID:

   sphinx-document

   项目 ID:

   sphinx-document-test_1_0

   项目网址:

   https://www.transifex.com/projects/p/sphinx-document-test_1_0/

3. 创建一个用于命令行的API令牌.

   前往你的 Transifex API 令牌 页面并生成一个令牌.现在复制生成的令牌,因为你之后将无法再次看到它.

4. 在用户配置文件中设置您的 Transifex API 令牌 $HOME/.transifexrc .

   [https://app.transifex.com]
   rest_hostname = https://rest.api.transifex.com
   token         = paste_your_api_token_here
   

5. 或者,您可以将您的 Transifex API 令牌存储为环境变量 TX_TOKEN ,该变量被 tx 识别和使用.

   $ export TX_TOKEN=paste_your_api_token_here
   

6. 为 tx 命令创建项目的配置文件.

   此过程将在当前目录中创建 .tx/config .

   $ cd /your/document/root
   $ tx init
   
   Successful creation of '.tx/config' file
   

7. 将 pot 文件上传到 Transifex 服务.

   通过使用 sphinx-intl update-txconfig-resources 将 pot 文件注册到 .tx/config 文件中,调整 --pot-dir 值至您的项目 pot 文件所在目录:

   $ cd /your/document/root
   $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
     --transifex-organization-name=sphinx-document \
     --transifex-project-name=sphinx-document-test_1_0
   

   您可以使用 SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME 和 SPHINXINTL_TRANSIFEX_PROJECT_NAME 环境变量代替相应的命令行参数.

   参见

   sphinx-intl update-txconfig-resources documentation

   并上传pot文件:

   $ tx push -s
   # Getting info about resources
   
   sphinx-document-test_1_0.builders - Getting info
   sphinx-document-test_1_0.builders - Done
   
   # Pushing source files
   
   sphinx-document-test_1_0.builders - Uploading file
   sphinx-document-test_1_0.builders - Done
   

8. 在Transifex上转发翻译.

9. 拉取翻译后的po文件并生成翻译后的HTML.

   获取翻译的目录并构建 mo 文件.例如,要为德语 (de) 构建 mo 文件:

   $ cd /your/document/root
   $ tx pull -l de
   # Getting info about resources
   
   sphinx-document-test_1_0.builders - Getting info
   sphinx-document-test_1_0.builders - Done
   
   # Pulling files
   
   sphinx-document-test_1_0.builders [de] - Pulling file
   sphinx-document-test_1_0.builders [de] - Creating download job
   sphinx-document-test_1_0.builders [de] - Done
   

   调用 make html （用于BSD/GNU make）,并传入语言代码:

   $ make -e SPHINXOPTS="-D language='de'" html
   

这就是全部!

小技巧

在本地和Transifex上进行翻译

如果您想推送所有语言的 po 文件,可以使用 tx push -t 命令来完成.请注意!此操作将覆盖 Transifex 中的翻译.

换句话说,如果您在服务和本地po文件中进行了更新,整合它们将需要花费大量时间和精力.

使用Weblate服务进行团队翻译

在 Weblate的文档 中了解更多信息.

贡献 Sphinx 的参考翻译

将新的贡献者翻译Sphinx参考文献的推荐方式是加入Transifex上的翻译团队.

Sphinx（主框架）文档有一个 sphinx 翻译页面 .

1. 登录到 Transifex 服务.

2. 请访问 sphinx 翻译页面 .

3. 点击 请求语言 并填写表格.

4. 等待Transifex Sphinx翻译维护者的接受.

5. （接受后）在Transifex上翻译.

详细信息在这里: https://help.transifex.com/zh/articles/6248698-getting-started-as-a-translator

翻译进度和统计

Added in version 7.1.0.

在渲染过程中,Sphinx 会为每个可翻译节点标记一个 translated 属性,指示该节点中的文本是否找到了翻译.

translation_progress_classes 配置值可用于根据 translated 属性的值为每个元素添加一个类.

The |translation progress| substitution can be used to display the percentage of nodes that have been translated on a per-document basis.

脚注

[1]

有关该软件套件的详细信息,请参见 GNU gettext 工具 .

[2]

因为没有人会想到西班牙宗教法庭!

Previous

HTML 主题

Next

Sphinx网页支持