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

1.12.0 · 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
  • el – Greek
  • en – English
  • eo – Esperanto
  • es – Spanish
  • et – Estonian
  • fa – Persian (Farsi)
  • fi – Finnish
  • fr – French
  • gl – Galician
  • 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.

Site language selector

7.0.0 · Default: none · Experimental

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

extra:
  alternate:
    - name: English
      link: /en/ # (1)
      lang: en
    - name: Deutsch
      link: /de/
      lang: de
  1. Note that this must be an absolute link. If it includes a domain part, it's used as defined. Otherwise the domain part of the site_url as set in mkdocs.yml is prepended to the link.

The following properties must be set for each alternate language:

name

Default: none · Required – This value of this property is used inside the language selector as the name of the language and must be set to a non-empty string.

link

Default: none · Required – This property must be set to an absolute link, which might also point to another domain or subdomain not necessarily generated with MkDocs.

lang

Default: none · Required – This property must contain an ISO 639-1 language code and is used for the hreflang attribute of the link, improving discoverability via search engines.

Language selector preview

Directionality

2.5.0 · Default: automatically set

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

theme:
  direction: ltr

Click on a tile to change the directionality:

Customization

Custom translations

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 the overrides folder. Then, import the translations of the language as a fallback and only adjust the ones you want to override:

<!-- Import translations for language and fallback -->
{% import "partials/languages/de.html" as language %}
{% import "partials/languages/en.html" as fallback %} <!-- (1) -->

<!-- Define custom translations -->
{% macro override(key) %}{{ {
  "source.file.date.created": "Erstellt am", <!-- (2) -->
  "source.file.date.updated": "Aktualisiert am"
}[key] }}{% endmacro %}

<!-- Re-export translations -->
{% macro t(key) %}{{
  override(key) or language(key) or fallback.t(key)
}}{% endmacro %}
  1. Note that en must always be used as a fallback language, as it's the default theme language.

  2. Check the list of available languages, pick the translation you want to override for your language and add them here.

theme:
  language: custom
Back to top