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

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

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

9.7.0

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/

No configuration is necessary.

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