国际化

1.1 新版功能.

作为Sphinx生成的消息(如导航栏)的翻译的补充,Sphinx提供了促进 文档 翻译的机制。有关配置的详细信息,请参阅 国际化选项

../../_images/translation.png

Sphinx中翻译的工作流可视化。 (棒图来源于 XKCD漫画 。)

Sphinx国际化细节

gettext 1 是国际化和本地化的既定标准。它天真地将程序中的消息映射到翻译的字符串。 Sphinx使用这些工具翻译整个文档。

最初项目维护者必须收集所有可翻译的字符串(也称为 消息 ),以使翻译人员知道它们。Sphinx通过调用 sphinx-build -b gettext 来提取这些。

doctree中的每个元素都将以单个消息结束,这会导致列表被平均分成不同的块,而大段落将保持原始文档中的粗粒度。这样可以为自由文本段落中的翻译人员提供无缝文档更新,同时仍然提供一些上下文。维护者的任务是分割太大的段落,因为没有合理的自动化方法。

在Sphinx成功运行 MessageCatalogBu​​ilder 后,您将在输出目录中找到 .pot 文件的集合。这些是 目录模板 ,包含原始语言 的邮件。

它们可以传递给翻译人员,翻译人员将把它们转换成 .po 文件—所谓的 消息目录 —包含从原始消息到外语字符串的映射。

gettext 出于效率原因将它们编译成称为 二进制目录的二进制格式 msgfmt 。如果你使用 locale_dirs 为你的 language 发现这些文件,Sphinx会自动选择它们。

例如:你的Sphinx项目中有一个文件 usage.rstgettext 构建器将其消息放入 usage.pot 。想象一下,您有西班牙语翻译 2 存储在 usage.po —为您的翻译版本需要按照以下说明操作:

  • 将您的消息目录编译到语言环境目录,比如说 locale ,所以它最终出现在源目录中的 ./ locale/es/LC_MESSAGES/usage.mo 中(其中 es 是语言西班牙语代码。):

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
    
  • 设置 locale_dirs["locale/"]

  • 设置 languagees (也可以通过 -D )。

  • 运行您想要的构建。

用sphinx-intl翻译

快速指南

sphinx-intl 是一个使用Sphinx翻译流程的有用工具。本节描述了使用 sphinx-intl 进行翻译的简便方法。

  1. 安装 sphinx-intl .

    $ pip install sphinx-intl
    
  2. 添加配置 conf.py .

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

    本案例研究假设 locale_dirs 设置为 locale/ 并且 gettext_compact 设置为 False (Sphinx文档已经配置为这样)。

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

    $ make gettext
    

    生成的pot文件将放在 _build/gettext 目录中。

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

    请注意不要破坏reST表示法。大多数编辑都会帮助你。

  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,请运行:

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

恭喜!您在 _build/html 目录中获得了翻译文档。

1.3 新版功能: 由make命令调用的 sphinx-build 会将po文件构建到mo文件中。

如果您使用的是1.2.x或更早版本,请在之前调用 sphinx-intl build 命令 make 命令。

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

如果文档已更新,则需要生成更新的pot文件并将差异应用于已翻译的po文件。要将更新从pot文件应用到po文件,请使用 sphinx-intl update 命令。

$ sphinx-intl update -p _build/locale

使用Transifex服务进行团队翻译

Transifex 是允许通过Web界面进行协作翻译的多种服务之一。它有一个漂亮的基于Python的命令行客户端,可以轻松获取和推送翻译。

  1. 安装 transifex-client.

    你需要 tx 命令来上传资源(pot文件)。

    $ pip install transifex-client
    
  2. 创建 transifex 帐户并为您的文档创建新项目。

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

    例如:

    项目ID

    sphinx-document-test_1_0

    项目网址

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

  3. tx 命令创建配置文件.

    这个过程将在当前目录中创建 .tx/config ,以及包含auth信息的 〜/.transifexrc 文件。

    $ tx init
    Creating .tx folder...
    Transifex instance [https://www.transifex.com]:
    ...
    Please enter your transifex username: <transifex-username>
    Password: <transifex-password>
    ...
    Done.
    
  4. 将pot文件上传到transifex服务。

    将pot文件注册到 .tx/config 文件:

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

    并上传pot文件:

    $ tx push -s
    Pushing translations for resource sphinx-document-test_1_0.builders:
    Pushing source file (locale/pot/builders.pot)
    Resource does not exist.  Creating...
    ...
    Done.
    
  5. 转发transifex的翻译。

  6. 拉出翻译的po文件并制作翻译的HTML。

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

    $ cd /your/document/root
    $ tx pull -l de
    Pulling translations for resource sphinx-document-test_1_0.builders (...)
     -> de: locale/de/LC_MESSAGES/builders.po
    ...
    Done.
    

    Invoke make html (对于BSD/GNU make):

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

就这样!

小技巧

在本地和Transifex上进行翻译

如果要推送所有语言的po文件,可以使用 tx push -t 命令完成。小心!此操作会覆盖transifex中的翻译。

换句话说,如果您更新了服务和本地po文件中的每一个,则需要花费很多时间和精力来集成它们。

有助于Sphinx参考翻译

新贡献者翻译Sphinx参考的推荐方法是加入Transifex的翻译团队。

有一个用于Sphinx(主)文档的 sphinx translation page

  1. 登录 transifex 服务。

  2. sphinx translation page .

  3. 点击 Request language and fill form.

  4. 等待transifex sphinx翻译维护者的接受。

  5. (接受后)翻译transifex。

脚注

1

有关该软件套件的详细信息,请参阅 GNU gettext实用程序

2

因为没有人期待西班牙宗教裁判所!