feat(material): add a special "null" locale to generated a fixed fix…

…ed item in the lang switcher (#270)

docs/setup/setting-up-material.md

@@ -23,6 +23,29 @@ plugins:
     reconfigure_material: true
 ```
 
+## Adding a special item in the language switcher
+
+If you want to add a special item in the automatically generated language switcher pointing to a fixed link, use the special `null` locale.
+
+``` yaml
+plugins:
+  - i18n:
+    languages:
+        - locale: en
+          name: English
+          build: true
+          default: true
+        - locale: fr
+          name: Français
+          build: true
+        - locale: null
+          name: Help translating
+          build: false
+          fixed_link: https://spaceship-prompt.sh/contribute/?h=trans#Translating
+```
+
+![spaceship prompt help translating](../assets/spaceship_help_translating_item.png){width=450}
+
 ## Features
 
 !!! failure "Incompatibility"
@@ -32,4 +55,4 @@ plugins:
 - [x] Automatic language switcher setup
 - [x] Automatic language switcher contextual link setup
 - [x] Search plugin localization and result deduplication
-- [x] Blog plugin localization
+- [ ] Blog plugin localization

mkdocs.yml

@@ -31,6 +31,7 @@ extra:
 
 markdown_extensions:
   - admonition
+  - attr_list
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.superfences

mkdocs_static_i18n/config.py

@@ -15,7 +15,7 @@ class Locale(config_options.Type):
 
     def run_validation(self, value):
         value = super().run_validation(value)
-        if not RE_LOCALE.match(value):
+        if not RE_LOCALE.match(value) and value.lower() != "null":
             raise ValidationError(
                 "Language code values must be either ISO-639-1 lower case "
                 "or represented with their territory/region/country codes, "
@@ -63,6 +63,19 @@ def validate(self):
                         ),
                     )
                 )
+        # special "null" locale can be used to insert an item in the language switcher
+        # so it must never be built
+        if self.locale == "null":
+            self.build = False
+            if self.fixed_link is None:
+                failed.append(
+                    (
+                        "fixed_link",
+                        ValidationError(
+                            f"languages[{self.locale}].fixed_link should be set to a valid URL."
+                        ),
+                    )
+                )
         return failed, warnings
 
 

mkdocs_static_i18n/reconfigure.py

@@ -294,7 +294,7 @@ def reconfigure_material_theme(self, config: MkDocsConfig, locale: str) -> MkDoc
         if "language" in config.theme._vars:
             config.theme._vars["language"] = locale
         # configure extra.alternate language switcher
-        if len(self.build_languages) > 1:
+        if len(self.build_languages) > 1 or "null" in self.all_languages:
             # 'on_page_context' overrides the config.extra.alternate
             # so we need to reset it to its initial computed value if present
             if self.extra_alternate:
@@ -303,9 +303,10 @@ def reconfigure_material_theme(self, config: MkDocsConfig, locale: str) -> MkDoc
             # warn if it's poorly configured
             if "alternate" in config.extra:
                 for alternate in config.extra["alternate"]:
-                    if not alternate.get("link", "").startswith("/") or not alternate.get(
-                        "link", ""
-                    ).endswith("/"):
+                    alternate_link = alternate.get("link", "")
+                    if not alternate_link.startswith("http") and (
+                        not alternate_link.startswith("/") or not alternate_link.endswith("/")
+                    ):
                         log.info(
                             "The 'extra.alternate' configuration contains a "
                             "'link' option that should be an absolute path '/' and "
@@ -329,10 +330,10 @@ def reconfigure_material_theme(self, config: MkDocsConfig, locale: str) -> MkDoc
                 # use_directory_urls = True
                 link_suffix = "" if config.get("use_directory_urls") else "index.html"
                 # setup language switcher
-                for language in self.build_languages:
+                for language in self.all_languages:
                     lang_config = self.get_language_config(language)
-                    # skip language if not built
-                    if lang_config.build is False:
+                    # skip language if not built unless we are the special "null" locale
+                    if lang_config.build is False and lang_config.locale != "null":
                         continue
                     config.extra["alternate"].append(
                         {

tests/test_control.py

@@ -132,6 +132,23 @@ def test_control_single(make_config, control_data, test_data):
                 },
             },
         ),
+        (
+            {"mkdocs_fp": "tests/structures/control/en_only/mkdocs.yml"},
+            {"mkdocs_fp": "tests/structures/control/fr_with_default/mkdocs.yml"},
+            {
+                "mkdocs_fp": "tests/mkdocs.yml",
+                "docs_dir": "docs_suffix_structure_two_languages/",
+                "plugins": {
+                    "i18n": {
+                        "languages": [
+                            {"locale": "en", "name": "test", "default": True},
+                            {"locale": "fr", "name": "test"},
+                            {"locale": "null", "name": "help", "build": True, "fixed_link": "https://ultrabug.fr"},
+                        ],
+                    }
+                },
+            },
+        ),
         (
             {"mkdocs_fp": "tests/structures/control/en_only/mkdocs.yml"},
             {"mkdocs_fp": "tests/structures/control/fr_with_default/mkdocs.yml"},
@@ -167,6 +184,24 @@ def test_control_single(make_config, control_data, test_data):
                 },
             },
         ),
+        (
+            {"mkdocs_fp": "tests/structures/control/en_only/mkdocs.yml"},
+            {"mkdocs_fp": "tests/structures/control/fr_with_default/mkdocs.yml"},
+            {
+                "mkdocs_fp": "tests/mkdocs.yml",
+                "docs_dir": "docs_folder_structure_two_languages_with_default/",
+                "plugins": {
+                    "i18n": {
+                        "docs_structure": "folder",
+                        "languages": [
+                            {"locale": "en", "name": "test", "default": True},
+                            {"locale": "fr", "name": "test"},
+                            {"locale": "null", "name": "help", "build": True, "fixed_link": "https://ultrabug.fr"},
+                        ],
+                    }
+                },
+            },
+        ),
     ],
 )
 def test_control_en_fr(

tests/test_language_selector.py

@@ -162,3 +162,28 @@ def test_plugin_language_selector_fixed_link_with_static_alternate():
         {"name": "français", "link": "/fr/", "lang": "fr"},
     ]
     build(mkdocs_config)
+
+
+def test_plugin_language_selector_with_null():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        theme={"name": "material"},
+        use_directory_urls=True,
+        docs_dir="docs_suffix_structure_two_languages/",
+        plugins={
+            "i18n": {
+                "languages": [
+                    {"locale": "en", "name": "english", "default": True},
+                    {"locale": "fr", "name": "français"},
+                    {"locale": "null", "name": "help", "fixed_link": "https://ultrabug.fr"},
+                ],
+            },
+        },
+    )
+    i18n_plugin = mkdocs_config["plugins"]["i18n"]
+    result = i18n_plugin.on_config(mkdocs_config)
+    assert result["extra"]["alternate"] == [
+        {"name": "english", "link": "/", "lang": "en"},
+        {"name": "français", "link": "/fr/", "lang": "fr"},
+        {"name": "help", "link": "https://ultrabug.fr", "lang": "null"}
+    ]

tests/test_languages_option.py

@@ -145,3 +145,103 @@ def test_plugin_languages_one_lang():
             "site_url": None,
         },
     ]
+
+
+def test_plugin_languages_null_no_fixed_link():
+    with pytest.raises(Abort):
+        load_config(
+            "tests/mkdocs.yml",
+            theme={"name": "mkdocs"},
+            use_directory_urls=True,
+            docs_dir="docs_suffix_structure_two_languages/",
+            plugins={
+                "i18n": {
+                    "languages": [
+                        {
+                            "locale": "en",
+                            "name": "english",
+                            "default": True,
+                        },
+                        {"locale": "fr", "name": "français"},
+                        {"locale": "null", "name": "help"},
+                    ],
+                },
+            },
+        )
+
+
+def test_plugin_languages_dual_lang_with_null():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        theme={"name": "mkdocs"},
+        use_directory_urls=True,
+        docs_dir="docs_suffix_structure_two_languages/",
+        plugins={
+            "i18n": {
+                "languages": [
+                    {
+                        "locale": "en",
+                        "name": "english",
+                        "default": True,
+                    },
+                    {"locale": "fr", "name": "français"},
+                    {"locale": "null", "name": "help", "fixed_link": "https://ultrabug.fr"},
+                ],
+            },
+        },
+    )
+    i18n_plugin = mkdocs_config["plugins"]["i18n"]
+    i18n_plugin.on_config(mkdocs_config)
+    assert i18n_plugin.config["languages"] == [
+        {
+            "locale": "en",
+            "name": "english",
+            "link": "/",
+            "fixed_link": None,
+            "build": True,
+            "default": True,
+            "nav": None,
+            "nav_translations": None,
+            "theme": None,
+            "site_name": None,
+            "copyright": None,
+            "extra": None,
+            "site_author": None,
+            "site_description": None,
+            "site_url": None,
+        },
+        {
+            "locale": "fr",
+            "name": "français",
+            "link": "/fr/",
+            "fixed_link": None,
+            "build": True,
+            "default": False,
+            "nav": None,
+            "nav_translations": None,
+            "theme": None,
+            "site_name": None,
+            "copyright": None,
+            "extra": None,
+            "site_author": None,
+            "site_description": None,
+            "site_url": None,
+        },
+        {
+            "locale": "null",
+            "name": "help",
+            "link": "/null/",
+            "fixed_link": "https://ultrabug.fr",
+            "build": False,
+            "default": False,
+            "nav": None,
+            "nav_translations": None,
+            "theme": None,
+            "site_name": None,
+            "copyright": None,
+            "extra": None,
+            "site_author": None,
+            "site_description": None,
+            "site_url": None,
+        },
+    ]