e1b77ab66e
A framework for translating themes as been added, which includes: 1. Use of Jinja's `i18n` plugin for translating phrases in templates (not page content). 2. A French translation of the built-in themes (contributions in other languages are welcome). 3. A new `theme.locale` option to define the locale/language of the site. 4. The search plugin uses the value of `theme.locale` as its default 'lang'. 5. Third party themes may chose to use the framework (use is optional). 6. A documented workflow for translating MkDocs built-in themes. 7. Custom tooling for use by translators and theme devs. The dependencies are not installed by default and are not needed to use MkDocs without translations. However, for anyone who wants to make use of the features, `pip install mkdocs[i18n]` will install all necessary dependencies. Relates to #211.
2.0 KiB
Localizing Your Theme
Display your theme in your preferred language.
!!! Note
Theme localization only translates the text elements of the theme itself
(such as "next" and "previous" links), not the actual content of your
documentation. If you wish to create multilingual documentation, you need
to combine theme localization as described here with a third-party
internationalization/localization plugin.
Installation
For theme localization to work, you must use a theme which supports it and
enable i18n (internationalization) support by installing mkdocs[i18n]:
pip install mkdocs[i18n]
Supported locales
In most cases a locale is designated by the ISO-639-1 (2-letter) abbreviation
for your language. However, a locale may also include a territory (or region or
county) code as well. The language and territory must be separated by an
underscore. For example, some possible locales for English might include en,
en_AU, en_GB, and en_US.
For a list of locales supported by the theme you are using, see that theme's documentation.
!!! Warning
If you configure a language locale which is not yet supported by the theme
that you are using, MkDocs will fall back to the theme's default locale.
Usage
To specify the locale that MkDocs should use, set the locale parameter of the theme configuration option to the appropriate code.
For example, to build the mkdocs theme in French you would use the following
in your mkdocs.yml configuration file:
theme:
name: mkdocs
locale: fr
Contributing theme translations
If a theme has not yet been translated into your language, feel free to contribute a translation using the Translation Guide.