翻译

主题本地化指南。

MkDocs 附带的内置主题支持翻译。这是一份面向翻译人员的指南，记录了如何贡献新的翻译和/或更新现有翻译的过程。有关修改现有主题的指导，请参阅贡献指南。要启用特定翻译，请参阅用户指南中关于您所使用主题的文档。对于第三方主题的翻译，请参阅这些主题的文档。第三方主题若要使用 MkDocs 的翻译工具和方法，必须正确配置以利用这些工具。

注意： 翻译仅适用于主题模板中包含的文本，例如“下一页”和“上一页”链接。页面的 Markdown 内容不会被翻译。如果您希望创建多语言文档，您需要结合主题本地化与第三方国际化/本地化插件。

本地化工具要求

主题本地化使用 babel 项目来生成和编译本地化文件。您需要从本地计算机的 git 工作树中进行操作，以使用翻译命令。

请参阅贡献指南，了解如何安装用于开发和提交拉取请求。本文档中的说明假设您正在使用正确配置的开发环境进行操作。

确保在您的环境中安装了翻译要求：

pip install 'mkdocs[i18n]'

为主题添加语言翻译

如果您的首选语言在某个（或两个）内置主题（mkdocs 和 readthedocs）中尚未得到支持，您可以轻松地通过以下步骤贡献翻译。

以下是您需要做的简要概述：

  1. 分叉并克隆 MkDocs 仓库，然后为开发安装 MkDocs 以添加和测试翻译。
  2. 初始化新的本地化目录 为您的语言（如果您的语言环境已有翻译，请按照更新主题本地化文件的说明操作）。
  3. 为本地化目录中的每个文本占位符添加翻译。
  4. 本地提供并测试 您语言的翻译主题。
  5. 更新文档 关于每个翻译主题支持的翻译。
  6. 通过拉取请求贡献您的翻译。

注意： 翻译语言环境通常使用 ISO-639-1（2 字母）语言代码标识。虽然也支持地区/区域/国家代码，但特定位置的翻译应在完成通用语言翻译后添加，并且区域方言需要使用与通用语言翻译不同的术语。

分叉并克隆 MkDocs 仓库

在以下步骤中，您将使用 MkDocs 仓库的分叉版本。请按照分叉和克隆 MkDocs 仓库的说明操作。

为了测试翻译，您还需要从您的分叉为开发安装 MkDocs。

初始化本地化目录

每个主题的模板包含已被提取到便携对象模板（messages.pot）文件中的文本占位符，该文件位于每个主题的文件夹中。

初始化目录包括运行一个命令，该命令将为您的目标语言创建目录结构，并从主题的 pot 文件派生出一个便携对象（messages.po）文件。

在每个主题的目录中使用 init_catalog 命令，并提供适当的语言代码（-l <language>）。

语言代码几乎总是两个小写字母，例如 sv，但在某些情况下需要进一步明确。

参见：

特别是，要知道 pt 语言应被明确为 pt_PT 和 pt_BR，是因为在 语言子标签注册表 页面中搜索 pt- 时会找到它。而 sv 应保持为 sv，因为该页面不包含 sv-。

因此，如果我们选择 es（西班牙语）作为示例语言代码，要为内置主题添加翻译，请运行以下命令：

pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es
pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es

上述命令将创建如下文件结构：

mkdocs/themes/mkdocs/locales
├── es
│   └── LC_MESSAGES
│       └── messages.po

现在你可以继续下一步，为本地化目录中的每个文本占位符添加翻译。

更新主题翻译

如果自上次为你的语言更新 messages.po 以来，主题的 messages.pot 模板文件已被[更新][update themes]，请按照以下步骤更新主题的 messages.po 文件：

  1. 更新主题的翻译目录以刷新每个主题的可翻译文本占位符。
  2. 翻译每个 messages.po 目录文件语言中新添加的可翻译文本占位符。
  3. 本地提供和测试你语言的翻译主题。
  4. 通过 Pull Request 贡献你的翻译。

更新翻译目录

此步骤应在主题模板[更新][update themes]后，为你愿意贡献翻译的每种语言完成。

要更新两个内置主题的 fr 翻译目录，请使用以下命令：

pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr
pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr

现在你可以继续下一步，为本地化目录中每个更新的文本占位符添加翻译。

翻译 MkDocs 主题

现在你的本地化 messages.po 文件已准备就绪，你需要做的就是在文件中为每个 msgid 项的每个 msgstr 项添加翻译。

msgid "Next"
msgstr "Siguiente"

警告： 不要修改 msgid，因为它对所有翻译都是通用的。只需在 msgstr 项中添加其翻译。

完成 po 文件中列出的所有术语的翻译后，你将希望测试你的本地化主题。

测试主题翻译

要测试带有翻译的主题，你需要首先将主题的 messages.po 文件编译为 messages.mo 文件。以下命令将编译两个内置主题的 es 翻译：

pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es
pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es

上述命令将生成以下文件结构：

mkdocs/themes/mkdocs/locales
├── es
│   └── LC_MESSAGES
│       ├── messages.mo
│       └── messages.po

请注意，编译的 messages.mo 文件是根据你刚刚编辑的 messages.po 文件生成的。

然后修改项目根目录下的 mkdocs.yml 文件以测试新的和/或更新的区域设置：

theme:
  name: mkdocs
  locale: es

最后，运行 mkdocs serve 以查看你的新本地化主题版本。

注意： 构建和发布过程会负责编译并分发所有区域设置给最终用户，因此你只需担心贡献实际的文本翻译 messages.po 文件（其余部分会被 git 忽略）。

在你完成测试工作后，请务必在提交更改前撤销对 mkdocs.yml 文件中 locale 设置的更改。

更新主题文档

选择你的主题页面会自动更新所有可用的区域设置选项。

贡献翻译

现在是时候将你的出色工作贡献给项目了。谢谢！