search

ultrabug / mkdocs-static-i18n

MkDocs i18n plugin using static translation markdown files
https://ultrabug.github.io/mkdocs-static-i18n/
MIT License
228 stars 38 forks source link

English pages shows in the Swedish menu #161

Open tirithen opened 1 year ago

tirithen commented 1 year ago

I'm working on a mkdocs site using this plugin. It solves a lot around localization, but when there is a file called my-page.en.md but NO my-page.sv.md the Swedish menu will list the English page (as a fallback?).

I would like it to only include the pages that has translations, and skip the other pages.

How can I configure i18n to do this?

ultrabug commented 1 year ago

Hello @tirithen ; indeed the design of this plugin is to always fallback to the default language because MkDocs itself has a build system that needs to create a navigation from a main directory tree (docs_dir).

So while you could have pages in Swedish that do not have a translation at all, you cannot avoid the fallback so far.

This could MAYBE be doable that being said but would require deep analysis and quite some time..

tirithen commented 1 year ago

It would have been very nice with an option flag so that the user could choose whether or not it should use a fallback language or not, as the end user that visits the page might not understand the language that they get presented with, and it therefore would have been better to not generate these fallback pages in the first place. It could have been an opt-in feature to not have it being a breaking change.

For now I will go for generating multiple sites instead of using this plugin as the solution I'm working on cannot have mixed languages.

Thank you for taking the time to answer!

The other features of this plugin is really nice and intuitive, such as the file name language suffixes, and sending the user to the same page when selecting a new language from the menu. :)

ultrabug commented 1 year ago

Thanks for this input @tirithen ; in your opinion what should happen in the given situations if where were to have an opt in configuration flag to disable default language fallback?

  1. the homepage of the site has no translation
  2. the mkdocs.yml lists a static nav: with non translated pages

Thanks for your kind words, I'm happy you considered using this plugin

tirithen commented 1 year ago

@ultrabug

I think that one clear option is to fail the build in both cases, putting an error message to the user that there are references to non-existing pages. It does not have to be a bad thing as if an index page is missing it would probably a pretty serious issue for the visitors of the website. Another advantage is that with good clear error messages this makes the behavior of the build command more clear and easy to understand for authors.

There are other possible variations where a missing index page would add an empty page, and missing pages listed under the nav: config might be silently excluded. But I'm thinking that this might lead to authors missing out on the configuration problem.

If you would go for the more strict configuration, the configuration flag could possible be called something like "strict" or similar rather than "disable language fallback" as well.

As the behavior is deterministic, and the cause of the error is clear I as a user would see no problem with the mkdocs build command failing to output any HTML as the website would anyway have had invalid or missing text content if the build would have continued running.