Changing the language¶

Material for MkDocs supports internationalization (i18n) and provides translations for template variables and labels in 40+ languages. Additionally, the site search can be configured to use a language-specific stemmer (if available).

Configuration¶

Site language¶

Source · Default: en

You can set the site language in mkdocs.yml with:

theme:
  language: en

The following languages are supported:

• af – Afrikaans
• ar – Arabic
• bn – Bengali (Bangla)
• ca – Catalan
• cs – Czech
• da – Danish
• de – German
• en – English
• eo – Esperanto
• es – Spanish
• et – Estonian
• fa – Persian (Farsi)
• fi – Finnish
• fr – French
• gl – Galician
• gr – Greek
• he – Hebrew
• hi – Hindi
• hr – Croatian
• hu – Hungarian
• id – Indonesian
• it – Italian
• ja – Japanese
• ka – Georgian
• kr – Korean
• my – Burmese
• nl – Dutch
• nn – Norwegian (Nynorsk)
• no – Norwegian
• pl – Polish
• pt – Portuguese
• ro – Romanian
• ru – Russian
• sh – Serbo-Croatian
• si – Slovenian
• sk – Slovak
• sr – Serbian
• sv – Swedish
• th – Thai
• tr – Turkish
• uk – Ukrainian
• vi – Vietnamese
• zh – Chinese (Simplified)
• zh-Hant – Chinese (Traditional)
• zh-TW – Chinese (Taiwanese)
• Add language

Note that some languages will produce unreadable anchor links, due to the way the default slug function works. Consider using a Unicode-aware slug function, as documented here.

Site language selector¶

Source · Experimental · Insiders only

If your documentation is available in multiple languages, a language selector can be added to the header next to the search bar. Languages can be defined via mkdocs.yml:

extra:
  alternate:
    - name: English
      link: https://squidfunk.github.io/mkdocs-material-insiders/en/
      lang: en
    - name: Deutsch
      link: https://squidfunk.github.io/mkdocs-material-insiders/de/
      lang: de
    - name: 日本語
      link: https://squidfunk.github.io/mkdocs-material-insiders/jp/
      lang: jp

This will render a language selector in the header next to the search bar:

This assumes that your project is structured into multiple subfolders, each of which contain the entire documentation for a given language, e.g.:

.
├─ en/
│  ├─ docs/
│  └─ mkdocs.yml
├─ de/
│  ├─ docs/
│  └─ mkdocs.yml
└─ jp/
   ├─ docs/
   └─ mkdocs.yml

Site search language¶

Source · Default: automatically set

Some languages, like Arabic or Japanese, need dedicated stemmers for search to work properly. Material for MkDocs relies on lunr-languages to provide this functionality. See the guide detailing how to set up site search for more information.

Directionality¶

Source · Default: automatically set

While many languages are read ltr (left-to-right), Material for MkDocs also supports rtl (right-to-left) directionality which is inferred from the selected language, but can also be set with:

theme:
  direction: ltr

Click on a tile to change the directionality:

Customization¶

Custom translations¶

Source · Difficulty: easy

If you want to customize some (or all) of the translations for your language, you may follow the guide on theme extension and create a new partial in partials/language, e.g. en-custom.html. Next, look up the translation you want to change in the base translation and add it to the partial.

Let's say you want to change "Table of contents" to "On this page":

{% macro t(key) %}{{ {
  "toc.title": "On this page"
}[key] }}{% endmacro %}

Then, add the following lines to mkdocs.yml:

theme:
  language: en-custom