国际化

在 1.1 版本加入.

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

../../_images/translation.svg

在Sphinx中实现翻译的工作流可视化。(该图由 plantuml 。)

狮身人面像国际化详情

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

最初,项目维护人员必须收集所有可翻译的字符串(也称为 messages )以使翻译人员了解这些信息。Sphinx通过调用 sphinx-build -b gettext

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

在Sphinx成功运行 MessageCatalogBuilder 您将找到一系列 .pot 您的输出目录中的文件。这些是 catalog templates 并包含以您的原始语言编写的邮件 only

它们可以被传递给翻译人员,从而将它们转换为 .po 文件-所谓的 message catalogs -包含从原始消息到外语字符串的映射。

gettext 将它们编译成称为 binary catalogs 穿过 msgfmt 出于效率的原因。如果使用以下命令使这些文件可供查找 locale_dirs 为了你的 language ,狮身人面像会自动取走它们。

例如:您有一份文档 usage.rst 在你的狮身人面像项目中。这个 gettext Builder将把它的消息放到 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 )。

  • 运行所需的构建。

为了防止出现错误,如果译文中的交叉引用与原文中的不匹配,则会发出警告。可以全局关闭它,方法是使用 suppress_warnings 配置变量。或者,要仅为一条消息关闭它,请在消息的末尾使用 #noqa 像这样::

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

(撰写 \#noqa 如果你想在文本中有“#noqa”字面意思的话。这不适用于代码块,其中 #noqa 被忽略,因为代码块无论如何都不包含引用。)

在 4.5 版本加入: 这个 #noqa 机制。

使用狮身人面像-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.
    

    此案例研究假设将BUILDDIR设置为 _buildlocale_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是多行文本,并包含reStrufredText语法:

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

    请注意不要打破休息记数法。大多数博客编辑会帮你做到这一点。

  6. 生成已翻译的文档。

    您需要一个 language 中的参数 conf.py 或者,您也可以在命令行上指定参数。

    对于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 版本加入: sphinx-build 由make命令调用的将把po文件构建到mo文件中。

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

翻译

使用新的POT文件更新您的PO文件

如果文档被更新,则需要生成更新的POT文件,并将差异应用于翻译后的PO文件。为了将POT文件中的更新应用到po文件,请使用 sphinx-intl update 指挥部。

$ sphinx-intl update -p _build/gettext

在团队翻译中使用TRANSPEX服务

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

  1. 安装 transifex-client

    你需要 tx 上载资源(POT文件)的命令。

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

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

    例如:

    项目ID:

    sphinx-document-test_1_0

    项目URL:

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

  3. 为创建配置文件 tx 指挥部。

    此过程将创建 .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文件上载到Tamerfex服务。

    将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. 将翻译转发到Tamerfex上。

  6. 拉取翻译后的PO文件,制作翻译后的超文本标记语言。

    获取翻译后的目录并构建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.
    

    调用 make html (适用于BSD/GNU制造):

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

就这样!

小技巧

在本地和在TRANSPEX上翻译

如果您想推送所有语言的po文件,可以使用 tx push -t 指挥部。小心!此操作将覆盖Transffex中的转换。

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

使用Weblate服务进行团队翻译

阅读更多信息 Weblate's documentation

对Sphinx参考翻译的贡献

建议新投稿人翻译Sphinx参考资料的方式是加入Transformfex上的翻译团队。

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

  1. 登录到 Transifex 服务。

  2. sphinx translation page

  3. 单击 Request language 并填写表格。

  4. 等待Tamerfex狮身人面像翻译维护人员的接受。

  5. (在接受后)在传递轴上平移。

详情请点击此处:https://docs.transifex.com/getting-started-1/translators

翻译进度和统计

在 7.1.0 版本加入.

在呈现过程中,Sphinx使用 translated 属性,指示是否为该节点中的文本找到了翻译。

这个 translation_progress_classes 配置值可用于向每个元素添加一个类,具体取决于 translated 属性。

这个 |translation progress| 替换可用于显示每个文档中已翻译的节点的百分比。

脚注