Multilingual setup

[weeblr]

Hi,

I am trying to setup a documentation site for several languages, deployed to GithubPages. I am aware of #2346 but this setup:

• seems a bit complex
• prevents us from using the local MkdMat docker container or just to serve multiple languages at the same time during dev

I believe the only thing preventing me from just having a /docs/en, /docs/de, /docs/fr series of folders, one per language, is the nav configuration element.

Per language pages should have their own navigation but as far as I can see, there can only be a single nav element in mkdocs.yml and we can't have separate ones per language.

I considered using {% if config.theme.language == 'xx' %} in templates but that does not work as navigation, just like content, is created by non-specialized users and cannot require changing templates just to add a menu link.

I'm missing something? is there a simpler configuration where all languages can be in a single place and we can serve them locally?

Thanks and best regards

[squidfunk]

You need to build one site per language, there's no way around it without getting overly hacky. #2346 is the way to go. Otherwise, all languages will be listed in the navigation. You can of course use the language selector, but you will have a section for each language.

[squidfunk]

Other than that, there's also the mkdocs-static-i18n plugin. We offer no official support for it, but it may help you achieve at least parts of what you're aiming for.

[weeblr]

ok, I replied without seeing your comment on that plugin. Would you consider it safe long-term? I'm not sure using a language code in the filename will work well for our audience (vs a separate folder entirely).

Think I'll go with separate sites and try find the most convenient way to run it locally.

[squidfunk]

I haven't used it, so it's probably a better idea to ask the author of the plugin. The reason why it's not officially supported is that I don't want to limit users in how they provide their different languages. The plugin assumes that you have a translation for each file, which might not be an assumption that generalizes well. Furthermore it might have troubles with features like instant loading. The language selector as it is currently implemented allows to even link non-MkDocs sites.

[weeblr]

The plugin assumes that you have a translation for each file, which might not be an assumption that generalizes well.

Indeed that would not work for us, at all. So I guess in a way having separate "sites", deployed on the same domain, does make sense.

[weeblr]

Thanks for your quick reply. Hmm, that's a bit unfortunate, it makes the multilingual setup a bit hard to use.

I am setting something up with a slightly different layout from #2346 but still locally the language switcher won't work.

Thanks again!