国际化#

本节介绍如何对 PyData Sphinx 主题进行国际化 (I18n) 和本地化 (L10n)。有关如何本地化 Sphinx 项目中可配置字符串的详细信息，请参阅 用户指南中关于国际化的部分.

PyData Sphinx 主题 I18n/i10n 工作流程基于 GNU Gettext，并使用 pybabel 来维护目录。由社区贡献的本地化在 Transifex 上管理。

注意

国际化 (或 I18n) 是使程序或应用程序能够识别并支持多种语言的过程。

本地化 (L10n) 是将本地化的程序或应用程序翻译成不同语言的过程，同时确保翻译对某种语言和文化习惯来说是正确的。

某个国家特定的文化习惯集的正式描述，以及针对相同语言的所有相关翻译，称为该语言或国家的区域设置。有关本地化和国际化的更多信息，请参阅 GNU gettext 概念.

对主题进行国际化和本地化的通用过程如下

  1. 将主题中的字符串标记为可本地化.

  2. 提取可本地化字符串 到消息目录模板 POT (PO 模板文件)。

  3. 从 POT 文件生成 PO 文件，用于 您要本地化的新的语言 (区域设置) (或 更新现有的本地化文件)。

  4. 编译消息目录 到二进制 MO 文件。

  5. 本地化主题.

本地化文件#

本地化过程中使用三种类型的文件

  1. PO 文件 (Portable Object，也称为消息目录) 将给定程序的每个原始可翻译字符串 (在 msgid 中定义) 与其在特定目标语言中的翻译 (在 msgstr 字段中定义) 关联起来。单个 PO 文件专门用于单个目标语言。

  2. MO (Machine Object) 文件是 PO 文件的二进制版本。

  3. POT (Portable Object Template) 文件类似于 PO 文件，但翻译为空。它们用作新语言的模板。

将字符串标记为可本地化#

主题组件和布局中的所有自然语言文本都必须标记为可本地化，以便以后可以将它们翻译 (或本地化) 成其他语言。例如，如果您添加一个带有文本下一页的按钮，则需要将此文本标记为可本地化。

HTML 模板 (位于 src/pydata_sphinx_theme/theme/ 目录)。为此，您可以使用 Jinja2 trans 块和/或 _() 函数在相应的 HTML 模板中将文本标记为可本地化

例如，要将文本下一页标记为可本地化，您将编写

<button type="button">
   {{- _("Next page") -}}
</button>

以这种方式标记的任何文本都将被 pybabel 发现，并用于生成本地化文件 (PO 文件)。

将文本标记为可本地化后，请完成本文档中更新本地化文件部分中概述的步骤。

有关在 jinja 模板中将字符串标记为可本地化的更多详细信息，请访问 Jinja2 文档.

提示

请记住，如果需要，手动转义变量。

有时，对本地化人员描述字符串来自哪里，或者它指的是名词还是动词，会很有帮助，尤其是在主题中难以找到字符串，或者字符串本身不是很有描述性时 (例如，非常短的字符串)。如果在字符串之前立即添加以 L10n: 开头的注释，该注释将添加到 PO 文件中，并对本地化人员可见。例如

{# L10n: Navigation button at the bottom of the page #}
<button type="button">
   {{- _("Next page") -}}
</button>

更新本地化文件#

在主题中添加或更改自然语言文本时，您必须更新消息目录以包含新的或更新的文本。请按照以下步骤操作

  1. 编辑自然语言文本，并确保它 标记为可本地化。

  2. 提取字符串并更新本地化文件 (POT 文件)

    # note this will by default update all the localization files for all the supported locales
tox run -e i18n-extract

这将使用您修改的语言的文本位置和文本的新信息更新本地化文件。

如果您只更改不可本地化的文本 (如 HTML 标记)，则 extract 命令只会更新可本地化字符串的位置 (行号)。更新位置是可选的 - 行号是为了通知人类翻译者，而不是执行本地化。但最佳实践是保持位置更新。

如果您更改可本地化字符串，则上述命令将提取新的或更新的字符串到本地化模板文件 (POT) 并执行新的或更新的字符串与本地化文件中的现有本地化之间的模糊匹配。如果存在模糊匹配，则在匹配条目之前添加类似 #, fuzzy 的注释，这意味着需要手动审查本地化并可能更新。如果在审查本地化后，您决定保留现有的本地化，则可以从条目中删除 #, fuzzy 注释。如果没有模糊匹配，它将添加新的本地化条目。您可以在 GNU gettext 手册 中了解有关模糊条目的更多信息。

编译本地化文件#

Gettext 不解析任何文本文件，它读取二进制格式以提高性能。要编译存储库中的最新 PO 文件，请运行

tox run -e i18n-compile

您也可以在一步中运行提取、更新和编译命令

tox run -m i18n

这将更新本地化文件并将它们编译成存储库中的二进制 MO 文件。但是，如果存在需要审查的模糊匹配，则编译将失败，您需要手动审查本地化。然后再次编译文件。

添加新语言#

具有现有 (可能不完整) 本地化的语言列表可在 src/pydata_sphinx_theme/locale 目录中找到。

要添加新语言，请按照以下步骤操作

  1. 确定新语言的 ISO 639-1 代码。

  2. 基于 POT 文件为这种新语言生成 PO 文件

    # for example, to add Quechua (ISO 639-1 code: qu)
tox -e i18n-new-locale -- qu

  3. 更新并编译本地化文件，如更新本地化文件和编译本地化文件部分所述。然后提交更改。

  4. 将主题本地化为新添加的语言 (请参阅 本地化主题)。

本地化主题#

我们在 Transifex 上的 PyData Sphinx 主题项目 上管理本地化。

要贡献本地化，请按照以下步骤操作

  1. 注册 Transifex 帐户。

  2. 加入 PyData Sphinx 主题项目。

  3. 选择您要本地化的语言。如果您要查找的语言未列出，则可以 在 GitHub 上打开问题请求它。然后您可以根据添加新语言部分中概述的步骤打开拉取请求以添加新语言。

  4. 现在您可以开始本地化主题了。如果您是 Transifex 的新手，您可以访问 Transifex 文档 以获取更多信息。

完成本地化后，PyData Sphinx 主题维护者将审查并批准它。

本地化技巧#

本地化短语，而不是单词#

完整的句子和从句必须始终是一个可本地化的字符串。否则，您可能会得到 next page 本地化为 suivant page，而不是 page suivante 等。

处理本地化中的变量和标记#

一个可本地化的字符串可以是固定字符串和变量的组合，例如，Welcome to the Spanish version of the site 是固定部分 Welcome to the 和 version of the site 以及变量部分 Spanish 的组合。

{% trans language=language %}
Welcome to the {{ language }} version of the site
{% endtrans %}

将变量绑定为 language=language 可确保字符串能够被正确地本地化，尤其是在不同语言环境中词序可能有所不同。上面的字符串将被提取为 Welcome to the %(language) version of the site。翻译人员在本地化主题时必须逐字使用 %(language)。

当一个块包含带有属性的 HTML 时，那些不需要本地化的属性应该作为参数传递。这样可以确保在这些属性更改时，字符串不需要重新本地化。

{% trans url="https://pydata.org/" %}
 Please visit <a href="{{ url }}" title="PyData website">the PyData website</a> for more information.
{% endtrans %}

参考资料#

I18N 和 L10N 是比较深奥的主题。这里，我们只涵盖完成基本技术任务所需的最低限度内容。您可能喜欢