Changing the language¶

Material for MkDocs supports internationalization (i18n) and provides translations for template variables and labels in 50+ 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
lv – Latvian
mn – Mongolian
ms – Bahasa Malaysia
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

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.

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:

overrides/partials/languages/custom.html mkdocs.yml

<!-- 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 %}

Note that en must always be used as a fallback language, as it's the default theme language.
Check the list of available languages, pick the translation you want to override for your language and add them here.

theme:
  language: custom