翻译

主题本地化指南。

与 MkDocs 捆绑在一起的 内置主题 提供了对翻译的支持。本指南面向翻译人员，介绍了贡献新翻译或更新现有翻译的过程。有关修改现有主题的指南，请参见 贡献指南。若要启用特定翻译，请参阅 用户指南 中关于您使用的特定主题的文档。对于第三方主题的翻译，请参阅这些主题的文档。为了使第三方主题使用 MkDocs 的翻译工具和方法，该主题必须正确地 配置 以便使用这些工具。

注意

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

本地化工具先决条件

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

请参阅 贡献指南，了解有关如何 为开发安装 和 提交拉取请求 的说明。本文档中的说明假设您正在从一个已正确配置的开发环境中工作。

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

pip install 'mkdocs[i18n]'

向主题添加语言翻译

如果您的首选语言区域设置尚未在两个内置主题（mkdocs 和 readthedocs）中的一个或两个上支持，您可以通过按照以下步骤轻松贡献翻译。

以下是您需要执行操作的简要概述

  1. Fork 并克隆 MkDocs 存储库，然后 安装 MkDocs 用于开发 以添加和测试翻译。
  2. 初始化新的本地化目录 用于您的语言（如果您的区域设置的翻译已经存在，请按照 更新主题本地化文件 的说明操作）。
  3. 添加翻译 用于本地化目录中的每个文本占位符。
  4. 本地服务和测试 用于您的语言的已翻译主题。
  5. 更新文档 关于每个已翻译主题的受支持翻译。
  6. 贡献您的翻译 通过拉取请求。

注意

翻译区域设置通常使用 ISO-639-1（2 个字母）语言代码来标识。虽然也支持区域/地区/国家/地区代码，但特定于位置的翻译应仅在完成一般语言翻译后以及区域方言需要使用与一般语言翻译不同的术语时添加。

Fork 并克隆 MkDocs 存储库

在以下步骤中，您将使用 MkDocs 存储库的分支。按照 Fork 并克隆 MkDocs 存储库 的说明操作。

若要测试翻译，您还需要从您的分支中 安装 MkDocs 用于开发。

初始化本地化目录

每个主题的模板都包含已提取到可移植对象模板 (messages.pot) 文件中的文本占位符，该文件位于每个主题的文件夹中。

初始化目录包括运行一个命令，该命令将为您的所需语言创建目录结构，并准备一个源自主题的 pot 文件的可移植对象 (messages.po) 文件。

对每个主题的目录使用 init_catalog 命令，并提供相应的语言代码 (-l <language>)。

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

请参阅

特别是，知道 pt 语言应该被区分成 pt_PT 和 pt_BR 的方法是，如果您在语言子标签注册表页面中搜索 pt-，则该页面会包含 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.pot 模板文件已 更新，并且自上次为您的区域设置更新 messages.po 以来，请按照以下步骤更新主题的 messages.po 文件

  1. 更新主题的翻译目录 以刷新每个主题的可翻译文本占位符。
  2. 翻译 您能够翻译的每个 messages.po 目录文件语言中新添加的可翻译文本占位符。
  3. 本地服务和测试 用于您的语言的已翻译主题。
  4. 贡献您的翻译 通过拉取请求。

更新翻译目录

在您已 更新 您愿意为其贡献翻译的每种语言的主题模板后，应完成此步骤。

若要更新两个内置主题的 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 设置的更改。

更新主题文档

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

贡献翻译

现在是您 贡献 您出色的工作到项目中的时候了。感谢您！