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
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 – 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 · 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:

    # 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:

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/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":

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

Then, add the following lines to mkdocs.yml:

theme:
  language: en-custom