Skip to content

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
  • bg – Bulgarian
  • 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
  • is – Icelandic
  • it – Italian
  • ja – Japanese
  • ka – Georgian
  • kr – Korean
  • mn – Mongolian
  • my – Burmese
  • nl – Dutch
  • nn – Norwegian (Nynorsk)
  • no – Norwegian
  • pl – Polish
  • pt – Portuguese
  • ro – Romanian
  • ru – Russian
  • sh – Serbo-Croatian
  • si – Sinhalese
  • sk – Slovak
  • sl – Slovenian
  • 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

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

extra:
  alternate:

    # Switch to English
    - name: English
      link: <your-site>/en/
      lang: en

    # Switch to German
    - name: Deutsch
      link: <your-site>/de/
      lang: de

    # Switch to Japanese
    - name: 日本語
      link: <your-site>/ja/
      lang: ja

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

Language selection

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 of the translations for a language, just follow the guide on theme extension and create a new partial in partials/languages, 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":

<!-- Use en language as fallback -->
{% import "partials/languages/en.html" as fallback %}
{% macro override(key) %}{{ {
  "toc.title": "On this page"
}[key] }}{% endmacro %}

<!-- Re-export the translation macro for mkbuild-material to use -->
{% macro t(key) %}{{ override(key) or fallback.t(key) }}{% endmacro %}

Then, add the following lines to mkdocs.yml:

theme:
  language: en-custom
Back to top