Skip to content

Changing the language

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


Site language

1.12.0 ยท Default: en

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

  language: en # (1)!
  1. HTML5 only allows to set a single language per document, which is why Material for MkDocs only supports setting a canonical language for the entire project, i.e. one per mkdocs.yml.

    The easiest way to build a multi-language documentation is to create one project in a subfolder per language, and then use the language selector to interlink those projects.

The following languages are supported:

  1. ๐Ÿ‡ฆ๐Ÿ‡ช Arabic ar Complete
  2. ๐Ÿ‡ฆ๐Ÿ‡ฒ Armenian hy Complete
  3. ๐Ÿ‡ฒ๐Ÿ‡พ Bahasa Malaysia ms 21 translations missing
  4. ๐Ÿ‡ง๐Ÿ‡ฉ Bengali (Bangla) bn Complete
  5. ๐Ÿ‡ง๐Ÿ‡ฌ Bulgarian bg Complete
  6. ๐Ÿ‡ช๐Ÿ‡ธ Catalan ca Complete
  7. ๐Ÿ‡จ๐Ÿ‡ณ Chinese (Simplified) zh Complete
  8. ๐Ÿ‡น๐Ÿ‡ผ Chinese (Taiwanese) zh-TW Complete
  9. ๐Ÿ‡จ๐Ÿ‡ณ Chinese (Traditional) zh-Hant Complete
  10. ๐Ÿ‡ญ๐Ÿ‡ท Croatian hr Complete
  11. ๐Ÿ‡จ๐Ÿ‡ฟ Czech cs Complete
  12. ๐Ÿ‡ฉ๐Ÿ‡ฐ Danish da Complete
  13. ๐Ÿ‡ณ๐Ÿ‡ฑ Dutch nl Complete
  14. ๐Ÿ‡บ๐Ÿ‡ธ English en Complete
  15. ๐Ÿ‡ซ๐Ÿ‡ท French fr Complete
  16. ๐Ÿ‡ฉ๐Ÿ‡ช German de Complete
  17. ๐Ÿ‡ฎ๐Ÿ‡ฑ Hebrew he Complete
  18. ๐Ÿ‡ฎ๐Ÿ‡ณ Hindi hi Complete
  19. ๐Ÿ‡ญ๐Ÿ‡บ Hungarian hu Complete
  20. ๐Ÿ‡ฎ๐Ÿ‡ธ Icelandic is Complete
  21. ๐Ÿ‡ฎ๐Ÿ‡ฉ Indonesian id Complete
  22. ๐Ÿ‡ฎ๐Ÿ‡น Italian it Complete
  23. ๐Ÿ‡ฏ๐Ÿ‡ต Japanese ja Complete
  24. ๐Ÿ‡ฎ๐Ÿ‡ณ Kannada kn Complete
  25. ๐Ÿ‡ฐ๐Ÿ‡ท Korean ko Complete
  26. ๐Ÿ‡ฎ๐Ÿ‡ถ Kurdish (Soranรฎ) ku-IQ 13 translations missing
  27. ๐Ÿ‡ฑ๐Ÿ‡น Lithuanian lt Complete
  28. ๐Ÿ‡ณ๐Ÿ‡ด Norwegian Bokmรฅl nb Complete
  29. ๐Ÿ‡ณ๐Ÿ‡ด Norwegian Nynorsk nn 14 translations missing
  30. ๐Ÿ‡ฎ๐Ÿ‡ท Persian (Farsi) fa Complete
  31. ๐Ÿ‡ต๐Ÿ‡ฑ Polish pl Complete
  32. ๐Ÿ‡ต๐Ÿ‡น Portuguese pt Complete
  33. ๐Ÿ‡ง๐Ÿ‡ท Portuguese (Brasilian) pt-BR Complete
  34. ๐Ÿ‡ท๐Ÿ‡ด Romanian ro Complete
  35. ๐Ÿ‡ท๐Ÿ‡บ Russian ru Complete
  36. ๐Ÿ‡ฎ๐Ÿ‡ณ Sanskrit sa Complete
  37. ๐Ÿ‡ท๐Ÿ‡ธ Serbo-Croatian sh 18 translations missing
  38. ๐Ÿ‡ช๐Ÿ‡ธ Spanish es Complete
  39. ๐Ÿ‡ธ๐Ÿ‡ช Swedish sv Complete
  40. ๐Ÿ‡ฎ๐Ÿ‡ณ Telugu te Complete
  41. ๐Ÿ‡น๐Ÿ‡ญ Thai th Complete
  42. ๐Ÿ‡น๐Ÿ‡ท Turkish tr Complete
  43. ๐Ÿ‡บ๐Ÿ‡ฆ Ukrainian uk Complete
  44. ๐Ÿ‡ต๐Ÿ‡ฐ Urdu ur Complete
  45. ๐Ÿ‡บ๐Ÿ‡ฟ Uzbek uz Complete
  46. ๐Ÿ‡ป๐Ÿ‡ณ Vietnamese vi Complete

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.

Translations missing? Help us out, it takes only 5 minutes

Material for MkDocs relies on outside contributions for adding and updating translations for the almost 60 languages it supports. If your language shows that some translations are missing, click on the link to add them. If your language is not in the list, click here to add a new language.

Site language selector

7.0.0 ยท Default: none

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.

    - 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 are available for each alternate language:


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.


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.


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


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:

  direction: ltr

Click on a tile to change the directionality:


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) %}{{ {
  "": "Erstellt am", <!-- (2)! -->
  "": "Aktualisiert am"
}[key] }}{% endmacro %}

<!-- Re-export translations -->
{% macro t(key) %}{{
  override(key) or language.t(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.

  language: custom