Switching between languages regression in 1.0.0

[kamilkrzyskow]

Continuation of #251

Environment:

• Windows 10
• Python 3.11.3
• pip freeze.txt

File structure

https://tree.nathanfriend.io/ ``` . ├── docs/ │ ├── some_dir/ │ │ └── some_more_dirs │ ├── index.md # Default language AND fallback │ ├── index.pl.md # Polish language │ └── index.cs.md # Czech language ├── overrides/ │ ├── assets/ │ │ ├── images/ │ │ ├── javascript/ │ │ └── stylesheets/ │ └── main.html └── mkdocs.yml ```

---

Language Toggling Issues: Given that each language now has an individual toggle for default, it's not feasible to set a single environment variable to toggle between them. In addition, swapping the values temporarily (e.g., en <-> pl) is currently not possible due to the existing file structure:

Exception: Conflicting files for the default language 'pl': choose either 'index.pl.md' or 'index.md' but not both

The new version connected the idea of default with fallback. This results in a conflict when I aim to use index.pl.md as the default, while intending index.md to act as a fallback for the English version. I certainly don't intend to alter the file structure to accommodate files like index.en.md.

Investigating the issue, I've confirmed for myself that the default language is closely related to the fallback, especially the default file without any suffix locale is always assumed to be using the default locale. I've tried some things to "revert" the behaviour to the previous way, but I either introduced a bug somewhere else (like for example the alternate switcher also now relies on the extension locale, I think) or the performance got worse.

So I've accepted that there needs to be some sort of compromise here between the new and old behaviour.

Locally, I've decided to add a global development_locale config option, which allows to forcefully override any other default and build options, so that the development locale would be the default and only language being built, additionally the development build avoids the conflicting files scenario by prioritizing the filename.locale.md files instead of the filename.md files.

This global option allows to quickly change the locale to a different one using environmental variables, and it allows to keep the older file structure setup while testing other languages. I don't need the option to build all of the languages using another language as the default one, because English (without extension) will always be used as the default one for the deployment.

---

To give more detail on how I was, and sort of will continue to use MkDocs, I did run it with this bash command:

export GMC_DEFAULT_LANG=pl export GMC_ONLY_DEFAULT_LANG=True; mkdocs serve

This set the environmental variables, which then were used in the mkdocs.yml config from version 0.56:

Part of the 0.56 i18n config

```md - i18n: default_language: !ENV [GMC_DEFAULT_LANG, en] default_language_only: !ENV [GMC_ONLY_DEFAULT_LANG, False] languages: en: name: en - English # Disable the /en/ path, a duplicate of the `default_language` build. build: false pl: name: pl - Polski build: true site_description: 'Gothic Modding Community to zbiór pomocnych materiałów do modowania gier Gothic i Risen.' cs: name: cs - Čeština build: true site_description: 'Dokumentace, návody a články zaměřené na modování her Gothic a Risen.' ```

This allowed me to easily change the language from en to pl and make the build time faster, without modifying the mkdocs.yml file.

---

In #254 I've proposed and implemented the development_locale global setting, which would partially restore the possibility of using such workflow. The change also uses files such as index.pl.md as the primary default and ignores file conflicts with index.md to use them as fallback.

Part of i18n config with new setting

```md - i18n: docs_structure: suffix development_locale: !ENV [GMC_DEV_LOCALE] languages: - name: en - English locale: en default: true build: true # nav_translations: # ... - name: pl - Polski locale: pl build: !ENV [GMC_ENABLE_ON_PUBLISH, GMC_BUILD_ALTERNATES, False] site_description: 'Gothic Modding Community to zbiór pomocnych materiałów do modowania gier Gothic i Risen.' # nav_translations: # ... - name: cs - Čeština locale: cs build: !ENV [GMC_ENABLE_ON_PUBLISH, GMC_BUILD_ALTERNATES, False] site_description: 'Dokumentace, návody a články zaměřené na modování her Gothic a Risen.' ```

So I can run it with:

export GMC_DEV_LOCALE=pl; mkdocs serve

[kamilkrzyskow]

Since there is no activity on the issue no comments or emojis, perhaps I have a one off use case, or a lot of people keep using the 0.56 version

I will close the issue in a week or 2, and accept I have to use a custom version of the plugin like I'm doing now.

[ultrabug]

Any use case is worth pushing. It's just that I do also have other things to attend to I'm sorry.

Doing my best and you're next in line since you've been asking for this for a while. The least I can do is to read, test and think about it to give you an answer.

[ultrabug]

Exception: Conflicting files for the default language 'pl': choose either 'index.pl.md' or 'index.md' but not both

This is indeed a bug on the reconfigure_files which was not taking into account the number of languages being built. In your case where you have only once, this should be allowed and accounted for.

The #269 PR should help us move forward. I'm not pretending it fixes everything this issue describes but I'd like us to agree on it first since you uncovered something :+1:

[kamilkrzyskow]

Thanks for your time investment and acknowledging that there is indeed a regression. I've checked out my docs with the 47c66bc515cf1cab4f997fa98e4bb7656483dbc4 commit and it allowed to switch to another language and the result was as expected. The only thing that's missing is an easy way to toggle/switch between languages without modifying the mkdocs.yml file each time there is a language change.

[ultrabug]

@kamilkrzyskow ok so I (finally) gave this a thought and I'd like to propose the following.

1. Introduce a new configuration option named build_only_locale
2. I would like this option to manipulate the config straight from the config.py in the I18nPluginConfig.validate method so we don't have to handle conditions in the rest of the code please

Would that sound okay? Do you want to do it and open a new PR or would you rather have me do it?

Thanks for your patience

[kamilkrzyskow]

Thanks a lot for your input. The idea sounds good to me. I shall open a new PR or modify my previous one in the coming days.