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 1 translations missing
2. Albanian sq 1 translations missing
3. Arabic ar 1 translations missing
4. Armenian hy 1 translations missing
5. Azerbaijani az 3 translations missing
6. Bahasa Malaysia ms 17 translations missing
7. Basque eu 1 translations missing
8. Belarusian be 1 translations missing
9. Bengali (Bangla) bn 1 translations missing
10. Bulgarian bg 1 translations missing
11. Burmese my 28 translations missing
12. Catalan ca 1 translations missing
13. Chinese (Simplified) zh 1 translations missing
14. Chinese (Taiwanese) zh-TW 1 translations missing
15. Chinese (Traditional) zh-Hant 1 translations missing
16. Croatian hr 1 translations missing
17. Czech cs 1 translations missing
18. Danish da 1 translations missing
19. Dutch nl 1 translations missing
20. English en Complete
21. Esperanto eo 1 translations missing
22. Estonian et 1 translations missing
23. Finnish fi 1 translations missing
24. French fr 1 translations missing
25. Galician gl 1 translations missing
26. Georgian ka 28 translations missing
27. German de Complete
28. Greek el 1 translations missing
29. Hebrew he 1 translations missing
30. Hindi hi 1 translations missing
31. Hungarian hu 1 translations missing
32. Icelandic is 1 translations missing
33. Indonesian id 1 translations missing
34. Italian it 1 translations missing
35. Japanese ja 1 translations missing
36. Kannada kn 1 translations missing
37. Korean ko 1 translations missing
38. Kurdish (Soranî) ku-IQ 14 translations missing
39. Latvian lv 1 translations missing
40. Lithuanian lt 1 translations missing
41. Luxembourgish lb 1 translations missing
42. Macedonian mk 1 translations missing
43. Mongolian mn 26 translations missing
44. Norwegian Bokmål nb 1 translations missing
45. Norwegian Nynorsk nn 1 translations missing
46. Persian (Farsi) fa 1 translations missing
47. Polish pl 1 translations missing
48. Portuguese pt 1 translations missing
49. Portuguese (Brasilian) pt-BR 1 translations missing
50. Romanian ro 1 translations missing
51. Russian ru 1 translations missing
52. Sanskrit sa 1 translations missing
53. Serbian sr 1 translations missing
54. Serbo-Croatian sh 6 translations missing
55. Sinhalese si 26 translations missing
56. Slovak sk 1 translations missing
57. Slovenian sl 1 translations missing
58. Spanish es 1 translations missing
59. Swedish sv 1 translations missing
60. Tagalog tl 4 translations missing
61. Tamil ta 1 translations missing
62. Telugu te 1 translations missing
63. Thai th 1 translations missing
64. Turkish tr 1 translations missing
65. Ukrainian uk 1 translations missing
66. Urdu ur 1 translations missing
67. Uzbek uz 1 translations missing
68. Vietnamese vi 1 translations missing

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.

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:

InsidersMaterial for MkDocs

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:

ltr rtl

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