国际化#

本节介绍如何对 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 文件 （便携对象，也称为消息目录）将给定程序的每个原始可翻译字符串（在 msgid 中定义）与其在特定目标语言中的翻译（在 msgstr 字段中定义）关联。一个 PO 文件专用于一个目标语言。

  2. MO （机器对象）文件是 PO 文件的二进制版本。

  3. POT （便携对象模板）文件类似于 PO 文件，但翻译为空。它们用作新语言的模板。

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

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

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

例如，要将文本 Next page 标记为可本地化，您可以编写：

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

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

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

For more details on marking strings as localizable in jinja templates visit the Jinja2 documentation.

小技巧

Remember to manually escape variables if needed.

有时，向本地化人员描述字符串的来源或它是指名词还是动词可能会有所帮助，特别是如果该字符串在主题中难以找到，或者字符串本身不太具有自描述性（例如，非常短的字符串）。如果您在字符串之前立即添加以 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. Sign up for a Transifex account.

  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 是深奥的主题。在这里，仅涵盖完成基本技术任务所需的最低限度。您可能会喜欢：