Why does MkDocs Material not use MkDocs standard locale config key?

[yves-chevallier]

On MkDocs documentation, to configure the language you have this:

theme: 
   name: mkdocs
   locale: fr

On the other hand on MkDocs Material you have this:

theme:
  name: material
  language: en

So for any multilingual plugins one should test both cases:

from toolz.dicttoolz import get_in
lang = (
    get_in(["theme", "language"], config)
    or get_in(["theme", "locale"], config)
    or get_in(["plugins", "search", "lang"], config)
    or "en"
)

Is there any particular reason why the setting does not follow MkDocs standard?

[kamilkrzyskow]

Hello @yves-chevallier,
most likely since Material for MkDocs had language years before MkDocs had locale:

• https://squidfunk.github.io/mkdocs-material/changelog/#1.12.0 (10/2017)
• https://www.mkdocs.org/about/release-notes/#support-added-for-theme-localization-2299 (06/2021)

So many people used language instead of locale in their configuration, so there could be some sort of regressions when changing it.
If I remember correctly, different language code formats are also used, one uses - and the other _ to separate sublanguages, but I could be wrong here.
The base.html could in theory create a mapping of locale to language and vice-versa internally for the theme to allow for both syntaxes, but I'm not sure about possible issues.

[squidfunk]

Correct, our (quite rudimentary) translation system that is based on Jinja templates predates MkDocs better implementation by several years. It was born out of a need to provide this functionality, since it wasn't considered for implementation in MkDocs itself, like many other features that Material for MkDocs ships that MkDocs does not have. We'll consolidate this functionality in the future. Until then, please just use language when using Material for MkDocs ☺️

There is still no possibility for themes (as this is a theme setting) to provide a bootstrap function, i.e., a function that is executed upon loading the theme after the configuration is resolved before it is passed to further plugins. We could in theory use this function to normalize configuration. Currently, there're only plugins and hooks, which all need user interaction. Thus, we cannot easily implement this functionality without a breaking change. I've asked the maintainers of MkDocs some time ago whether it would be possible to allow themes to provide out-of-plugin code, but it was turned down, again.

[kamilkrzyskow]

Oh right, my idea with using base.html doesn't help with the plugins as this change happens too late.

So for any multilingual plugins one should test both cases:

So instead of checking both variants the plugin makers can also sync the values themselves in on_config, so the rest of the plugin can just reference one value.

Personally I'm not a fan of this get_in(["plugins", "search", "lang"], config) as this looks like some sort of recursive function. No matter how fast Python 3.12 or 3.13 become, each function call in Python is more expensive than in other languages. So if such get_in runs in some on_page event then it could visibly impact performance on huge docs projects. Better to reference directly.

a function that is executed upon loading the theme after the configuration is resolved before it is passed to further plugins
[...]
I've asked the maintainers of MkDocs some time ago whether it would be possible to allow themes to provide out-of-plugin code, but it was turned down

Weird that it was turned down, as it shouldn't require much refactoring, I would assume it could work in similar fashion to how on_startup runs after config creation and before the rest of the build cycle
It also wouldn't make MkDocs less secure allowing "running arbitrary" code for the themes, as currently themes can run code in their __init__.py when imported into MkDocs, but that doesn't help here with changing the config 🤔