国际化

1.1 新版功能.

作为对Sphinx生成的消息(如导航栏)提供的翻译的补充,Sphinx提供了促进*文档*翻译的机制。有关配置的详细信息,请参阅:ref:intl options

../../_images/translation.svg

Workflow visualization of translations in Sphinx. (The figure is created by plantuml.)

sphinx国际化细节

**gettext**[1]u是国际化和本地化的既定标准。它天真地将程序中的消息映射到翻译后的字符串。斯芬克斯使用这些工具翻译整个文件。

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

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

在Sphinx成功运行:类之后:`~sphinx.builders.gettext.MessageCatalogBuilder`您将在输出目录中找到一组“.pot”文件。这些是**目录模板**,只包含您的原始语言*的消息*。

它们可以被传递给翻译程序,翻译程序会将它们转换成`.po``文件,即所谓的**消息目录**,其中包含从原始消息到外语字符串的映射。

*为了提高效率,gettext*将它们编译成一种称为**二进制目录**的二进制格式:program:`msgfmt’。如果您使用:confval:`locale_dirs`为您的:confval:`language`设置这些文件的可发现性,Sphinx将自动提取它们。

例如:你有一份文件``usage.rst``在你的Sphinx项目中。gettext*生成器将把它的消息放入``usage.pot``. 假设您在中存储了西班牙语翻译[2]``usage.po``需要按照以下说明进行编译:

  • 将您的消息目录编译到一个locale目录中,比如“locale”,这样它就以`./locale/es/LC峎MESSAGES结束/用法.mo``在源目录中(其中“es”是西班牙语的语言代码):

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

  • Set language to es (also possible via -D).

  • 运行所需的构建。

用sphinx国际翻译

快速指南

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

    这个案例研究假设BUILDDIR被设置为’u build``,:confval:`locale_dirs`被设置为``locale/``并且:confval:`gettext_compact`被设置为`False``(Sphinx文档已经这样配置)。

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

    $ make gettext
    

    生成的pot文件将被放在``u build/gettext``目录中。

  4. 生成采购订单文件。

    我们将使用上述步骤中生成的pot文件。

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

    完成后,生成的采购订单文件将放在以下目录中:

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. 翻译采购订单文件。

    As noted above, these are located in the ./locale/<lang>/LC_MESSAGES directory. An example of one such file, from Sphinx, builders.po, is given below.

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

    另一种情况是,msgid是多行文本,并包含restructedText语法:

    # 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符号。大多数po编辑都会帮你。

  6. 生成翻译文档。

    您需要一个:confval:`language`参数``conf.py``也可以在命令行中指定参数。

    对于For BSD/GNU make,运行:

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

    对于Windows:命令:命令提示符,运行:

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

    为PowerShell运行:

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

祝贺你!翻译后的文档在``u build/html``目录下。

1.3 新版功能: :程序:make命令调用的“sphinx build”将把po文件生成mo文件。

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

翻译

用新的pot文件更新你的po文件

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

$ sphinx-intl update -p _build/gettext

使用Transifex服务进行团队翻译

Transifex_x是允许通过web界面进行协作翻译的几种服务之一。它有一个漂亮的基于Python的命令行客户机,使得获取和推送翻译变得很容易。

  1. 安装 transifex-client.

    您需要:command:`tx`命令来上载资源(pot文件)。

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

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

    例如:

    项目ID

    sphinx-document-test_1_0

    项目URL

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

  3. 为:command:`tx`command创建配置文件。

    此进程将在当前目录中创建“.tx/config”,以及包含身份验证信息的“~/.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. 拉翻译后的采购订单文件,并制作翻译的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文件,可以使用:command:tx push-t command完成。小心!此操作覆盖transifex中的翻译。

换句话说,如果您已经更新了服务和本地po文件中的每一个文件,那么集成它们将花费大量的时间和精力。

有助于sphinx参考翻译

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

There is a sphinx translation page for Sphinx (master) documentation.

  1. 登录transifex服务。

  2. 去sphinx翻译页面

  3. 单击“请求语言”并填写表单。

  4. 等待sphinx翻译公司验收。

  5. (验收后)在transifex上翻译。

Detail is here: https://docs.transifex.com/getting-started-1/translators

脚注

1

请参见`GNU gettext实用程序<https://www.gnu.org/software/gettext/manual/gettext.html简介>`_有关该软件套件的详细信息。

2

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