Unusual navigation behavior when using insiders with static-i18n plugin

[NeilHanlon]

Context

https://github.com/rocky-linux/docs.rockylinux.org/ (mkdocs config)
https://github.com/rocky-linux/documentation/ (content)

Multiple languages supported and translated

Bug description

When using mkdocs-material-insiders with mkdocs-static-i18n plugin, there is nondeterministic behavior when navigating to a path which starts with an ISO 3166 country code.

For example, given a path /desktop/ which has other folders/files underneath it--navigating to this link by clicking on the link in the Nav bar from the index sends the user to /de/ (the index for our German translation), instead of to the /desktop/ page in english. Navigating to the /desktop/ page directly, or from any other page, is seemingly unaffected. Reverting to mkdocs-material (not insiders) causes this behavior to not reproduce.

Related links

n/a

Reproduction

9.5.18+insiders.4.53.6-nondeterministic-navigation-with-i18n.zip

Steps to reproduce

1. From the index page of the reproducer, navigate to the index page for the 'Desktop' category
2. URL will change to /de/ instead of /desktop/ - future navigation is now in German

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[NeilHanlon]

n.b. this is not specific to de; the same happens with fr and a word with a fr prefix.

I opened the issue against mkdocs-material as the only way I can reproduce is using an insiders build, but it's possible this is a behavior that needs adjusting in the static-i18n plugin.

[squidfunk]

Thanks for reporting and the excellent reproduction! I think I have a fix in c6a1521 for the prefix matching problem. I'm giving this issue the perfect badge, since it includes all necessary information and immediately demonstrates the problem.

There are further problems with the way the static-i18n plugin and Material for MkDocs work together. For instance, Material for MkDocs currently follows the approach to set only the top-level en/ and de/ paths as rel=alternate links, whereas the static-i18n plugin sets them to their specific pages. One can say, that the latter is better, but it's only possible because the static-i18n plugin builds all of your documentation projects together in one go. Material for MkDocs follows a loose-coupling approach where each language version of a site can be updated independently, and the author just needs to specify the main entrypoints via extra.alternate. Material for MkDocs will fetch the latest sitemap.xml and check if there's a corresponding mapping for the site, which is different from the modus operandi of the static-i18n plugin.

We've lately released the projects plugin, which is our take on agnostic multi-project setups, including multi-lingual documentation (although still heavy work in progress). Projects are meant to be loosely coupled and can be languages, versions, you name it – anything. If you open the browser console, you see warning messages generated because the sitemap.xml paths are off. You might take this upstream, but I'm not sure whether it can be nicely solved. There also an open PR on which we hope to gather more feedback that improves linking of alternate languages in https://github.com/squidfunk/mkdocs-material-insiders/pull/75.

We'll take this intel with us when we go back to the drawing board to see how we can make multi-lingual setups any simpler. We do not officially support the static-i18n plugin, so this is a little out of scope for us. However, if the static-i18n plugin could somehow tell the application where the sitemap.xml of the sites are located, we might make it able to better work together. Essentially, the static-i18n plugin should

In the meantime, we're regarding this issue as resolved (please confirm) and will come back to it, as said.

[NeilHanlon]

I will test this out, but it looks like it should fix the problem.

Thank you so much for the quick response!

We (the rocky project) will be testing out the Projects plugin soon for our wiki.rockylinux.org site, combining multiple distinct team/SIG wikis into a single space. Will definitely share what we come up with.

re: the i18n plugin -- agreed. It would be great if that were possible. There are some additional efficiencies which I think might help decrease overall generated HTML size for large multi-lingual sites (ultrabug/mkdocs-static-i18n#295, but I need to get back to the Maintainer...)

Thanks again!

[squidfunk]

Released as part of 9.5.19+insiders-4.53.7.