翻译¶

主题本地化指南。

MkDocs中包含的内置主题提供了翻译支持。 这是一个翻译指南，它记录了贡献新翻译和/或更新现有翻译的过程。 有关修改现有主题的指导，请参阅贡献指南。 要启用特定的翻译，请参阅用户指南中关于您正在使用的特定主题的文档。 有关第三方主题的翻译，请参阅这些主题的文档。 第三方主题要想使用MkDocs的翻译工具和方法，必须正确配置该主题才能使用这些工具。

本地化工具先决条件¶

Theme localization makes use of the babel project for generation and compilation of localization files. You will need to be working from the git working tree on your local machine to make use of the translation commands.

See the Contributing Guide for direction on how to Install for Development and Submit a Pull Request. The instructions in this document assume that you are working from a properly configured development environment.

Make sure translation requirements are installed in your environment:

pip install mkdocs[i18n]

将语言翻译添加到主题¶

If your favorite language locale is not yet supported on one (or both) of the built-in themes (mkdocs and readthedocs), you can easily contribute a translation by following the steps below.

Here is a quick summary of what you'll need to do:

1. Initialize new localization catalogs for your language (if a translation for your locale already exists, follow the instructions for updating theme localization files instead).
2. Add a translation for every text placeholder in the localized catalogs.
3. Locally serve and test the translated themes for your language.
4. Update the documentation about supported translations for each translated theme.
5. Contribute your translation through a Pull Request.

初始化本地化目录¶

The templates for each theme contain text placeholders that have been extracted into a Portable Object Template (messages.pot) file, which is present in each theme's folder.

Initializing a catalog consists of running a command which will create a directory structure for your desired language and prepare a Portable Object (messages.po) file derived from the pot file of the theme.

Use the init_catalog command on each theme's directory and provide the appropriate language code (-l <language>). For example, to add a translation for the Spanish es language to the mkdocs theme, run the following command:

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

The above command will create the following file structure:

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

You can now move on to the next step and add a translation for every text placeholder in the localized catalog.

更新主题翻译¶

If a theme's messages.pot template file has been updated since the messages.po was last updated for your locale, follow the steps below to update the theme's messages.po file:

1. Update the theme's translation catalog to refresh the translatable text placeholders of each theme.
2. Translate the newly added translatable text placeholders on every messages.po catalog file language you can.
3. Locally serve and test the translated themes for your language.
4. Contribute your translation through a Pull Request.

Updating the translation catalogs¶

This step should be completed after a theme template have been updated for each language that you are comfortable contributing a translation for.

To update the fr translation catalog of the mkdocs theme, use the following command:

pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales --locale fr

You can now move on to the next step and add a translation for every updated text placeholder in the localized catalog.

Translating the MkDocs themes¶

Now that your localized messages.po files are ready, all you need to do is add a translation in each msgstr item for each msgid item in the file.

msgid "Next"
msgstr "Siguiente"

Once you have finished translating all of the terms listed in the po file, you'll want to test your localized theme.

Testing theme translations¶

To test a theme with translations, you need to first compile the messages.po files of your theme into messages.mo files. The following command will compile the es translation for the mkdocs theme.

pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales --locale es

The above command results in the following file structure:

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

Note that the compiled messages.mo file was generated based on the messages.po file that you just edited.

Then modify the mkdocs.yml file at the root of the project to test the new and/or updated locale:

theme:
    name: mkdocs
    locale: es

Finally, run mkdocs serve to check out your new localized version of the theme.

更新主题文档¶

Update the lists of supported translations for each translated theme located at Choosing your theme (docs/user-guide/choosing-your-theme.md), in their locale options.

贡献翻译¶

It is now time for you to contribute your nice work to the project. Thank you!