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.

Configuration

Site language

1.12.0 en

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

theme:
  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. 🇿🇦 Afrikaans af Complete
  2. 🇦🇪 Arabic ar Complete
  3. 🇦🇲 Armenian hy Complete
  4. 🇲🇾 Bahasa Malaysia ms 16 translations missing
  5. 🇪🇸 Basque eu Complete
  6. 🇧🇾 Belarusian be Complete
  7. 🇧🇩 Bengali (Bangla) bn Complete
  8. 🇧🇬 Bulgarian bg Complete
  9. 🇪🇸 Catalan ca Complete
  10. 🇨🇳 Chinese (Simplified) zh Complete
  11. 🇹🇼 Chinese (Taiwanese) zh-TW Complete
  12. 🇨🇳 Chinese (Traditional) zh-Hant Complete
  13. 🇭🇷 Croatian hr Complete
  14. 🇨🇿 Czech cs Complete
  15. 🇩🇰 Danish da Complete
  16. 🇳🇱 Dutch nl Complete
  17. 🇺🇸 English en Complete
  18. 🇪🇺 Esperanto eo Complete
  19. 🇫🇮 Finnish fi Complete
  20. 🇫🇷 French fr Complete
  21. 🇩🇪 German de Complete
  22. 🇬🇷 Greek el Complete
  23. 🇮🇱 Hebrew he Complete
  24. 🇮🇳 Hindi hi Complete
  25. 🇭🇺 Hungarian hu Complete
  26. 🇮🇸 Icelandic is Complete
  27. 🇮🇩 Indonesian id Complete
  28. 🇮🇹 Italian it Complete
  29. 🇯🇵 Japanese ja Complete
  30. 🇮🇳 Kannada kn Complete
  31. 🇰🇷 Korean ko Complete
  32. 🇮🇶 Kurdish (Soranî) ku-IQ 13 translations missing
  33. 🇱🇹 Lithuanian lt Complete
  34. 🇱🇺 Luxembourgish lb Complete
  35. 🇲🇰 Macedonian mk Complete
  36. 🇳🇴 Norwegian Bokmål nb Complete
  37. 🇳🇴 Norwegian Nynorsk nn Complete
  38. 🇮🇷 Persian (Farsi) fa Complete
  39. 🇵🇱 Polish pl Complete
  40. 🇵🇹 Portuguese pt Complete
  41. 🇧🇷 Portuguese (Brasilian) pt-BR Complete
  42. 🇷🇴 Romanian ro Complete
  43. 🇷🇺 Russian ru Complete
  44. 🇮🇳 Sanskrit sa Complete
  45. 🇷🇸 Serbo-Croatian sh 5 translations missing
  46. 🇸🇰 Slovak sk Complete
  47. 🇸🇮 Slovenian sl Complete
  48. 🇪🇸 Spanish es Complete
  49. 🇸🇪 Swedish sv Complete
  50. 🇮🇳 Tamil ta Complete
  51. 🇮🇳 Telugu te Complete
  52. 🇹🇭 Thai th Complete
  53. 🇹🇷 Turkish tr Complete
  54. 🇺🇦 Ukrainian uk Complete
  55. 🇵🇰 Urdu ur Complete
  56. 🇺🇿 Uzbek uz Complete
  57. 🇻🇳 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 more than 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

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

name

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

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

lang

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

Stay on page

insiders-4.47.0

Insiders improves the user experience when switching between languages, e.g., if language en and de contain a page with the same path name, the user will stay on the current page:

docs.example.com/en/     -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/foo/
docs.example.com/en/bar/ -> docs.example.com/de/bar/
docs.example.com/en/     -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/
docs.example.com/en/bar/ -> docs.example.com/de/

No configuration is necessary. We're working hard on improving multi-language support in 2024, including making switching between languages even more seamless in the future.

Directionality

2.5.0

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.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.

theme:
  language: custom