Allow to translate site_name and site_description (#46)

* Allow to translate `site_name` and `site_description`

* Document new config setting

* Fix error setting language for mkdocs-material theme

* Add tests

* Add description to translated homepages using mkdocs and readthedocs themes

Author: mondeja

.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["redhat.vscode-yaml"],
+  "unwantedRecommendations": []
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  }
+}

docs/locale/es/_compendium.po

@@ -2,6 +2,9 @@
 msgid ""
 msgstr ""
 
+msgid "Mkdocs plugin for translations using PO files"
+msgstr "Plugin de Mkdocs para traducciones usando archivos PO"
+
 msgid "Permanent link"
 msgstr "Link permanente"
 

docs/locale/es/config.md.po

@@ -246,3 +246,24 @@ msgstr "Filtrar por porcentaje"
 
 msgid "Filter by number of messages"
 msgstr "Filtrar por número de mensajes"
+
+msgid ""
+"Configuration settings to translate. Currently only the next settings are "
+"supported:"
+msgstr ""
+"Parámetros de configuración a traducir. Actualmente sólo están soportados "
+"los siguientes parámetros:"
+
+msgid ""
+"[mkdocs-config-site_name]: https://www.mkdocs.org/user-"
+"guide/configuration/#site_name"
+msgstr ""
+"[mkdocs-config-site_name]: https://www.mkdocs.org/user-"
+"guide/configuration/#site_name"
+
+msgid ""
+"[mkdocs-config-site_description]: https://www.mkdocs.org/user-"
+"guide/configuration/#site_description"
+msgstr ""
+"[mkdocs-config-site_description]: https://www.mkdocs.org/user-"
+"guide/configuration/#site_description"

docs/src/config.md

@@ -192,6 +192,17 @@ The context for the template includes:
 
 ## Content
 
+<!-- mdpo-disable-next-line -->
+### **`translate`** (*list[str]*)
+
+Configuration settings to translate. Currently only the next settings are
+supported:
+
+<!-- mdpo-disable -->
+- [`site_name`][mkdocs-config-site_name]
+- [`site_description`][mkdocs-config-site_description]
+<!-- mdpo-enable -->
+
 <!-- mdpo-disable-next-line -->
 ### **`cross_language_search`** (*bool*)
 
@@ -291,3 +302,5 @@ this list.
 [mkdocs-material-site-language-selector]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector
 [jinja2-template]: https://jinja2docs.readthedocs.io/en/stable/templates.html
 [polib.POFile]: https://polib.readthedocs.io/en/latest/api.html#polib.POFile
+[mkdocs-config-site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
+[mkdocs-config-site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description

examples/material-theme/docs/locale/es/_compendium.po

@@ -2,5 +2,11 @@
 msgid ""
 msgstr ""
 
+msgid "Example using mkdocs-material theme with mkdocs-mdpo-plugin"
+msgstr "Ejemplo usando el tema mkdocs-material con mkdocs-mdpo-plugin"
+
+msgid "mkdocs-mdpo-plugin Material theme example"
+msgstr "Ejemplo de tema Material con mkdocs-mdpo-plugin"
+
 msgid "Some content"
 msgstr "Algo de contenido"

examples/material-theme/docs/locale/fr/_compendium.po

@@ -2,5 +2,11 @@
 msgid ""
 msgstr ""
 
+msgid "Example using mkdocs-material theme with mkdocs-mdpo-plugin"
+msgstr "Exemple utilisant le thème mkdocs-material avec mkdocs-mdpo-plugin"
+
+msgid "mkdocs-mdpo-plugin Material theme example"
+msgstr "mkdocs-mdpo-plugin exemple de Material thème"
+
 msgid "Some content"
 msgstr "Du contenu"

examples/material-theme/mkdocs.yml

@@ -1,4 +1,5 @@
-site_name: mkdocs-mdpo-plugin Material example
+site_name: mkdocs-mdpo-plugin Material theme example
+site_description: Example using mkdocs-material theme with mkdocs-mdpo-plugin
 site_url: https://mkdocs-mdpo.ga
 docs_dir: docs/src
 edit_uri: tree/master/docs/src
@@ -17,6 +18,9 @@ plugins:
   - mdpo:
       cross_language_search: false
       locale_dir: ../locale
+      translate:
+        - site_name
+        - site_description
 
 extra:
   alternate:

examples/mkdocs-theme/docs/locale/es/_compendium.po

@@ -0,0 +1,9 @@
+#
+msgid ""
+msgstr ""
+
+msgid "Example using builtin Mkdocs theme with mkdocs-mdpo-plugin"
+msgstr "Ejemplo usando el tema incluido en Mkdocs con mkdocs-mdpo-plugin"
+
+msgid "mkdocs-mdpo-plugin Mkdocs theme example"
+msgstr "Ejemplo con tema Mkdocs para mkdocs-mdpo-plugin"

examples/mkdocs-theme/docs/locale/fr/_compendium.po

@@ -0,0 +1,9 @@
+#
+msgid ""
+msgstr ""
+
+msgid "Example using builtin Mkdocs theme with mkdocs-mdpo-plugin"
+msgstr "Exemple utilisant le thème Mkdocs intégré avec mkdocs-mdpo-plugin"
+
+msgid "mkdocs-mdpo-plugin Mkdocs theme example"
+msgstr "mkdocs-mdpo-plugin exemple de Mkdocs thème"

examples/mkdocs-theme/mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: mkdocs-mdpo-plugin Mkdocs theme example
+site_description: Example using builtin Mkdocs theme with mkdocs-mdpo-plugin
 site_url: https://mkdocs-mdpo.ga
 docs_dir: docs/src
 
@@ -15,3 +16,6 @@ plugins:
         - fr
       cross_language_search: false
       locale_dir: ../locale
+      translate:
+        - site_name
+        - site_description

mkdocs.yml

@@ -83,6 +83,8 @@ plugins:
       locale_dir: ../locale
       cross_language_search: false
       min_translated_messages: 95%
+      translate:
+        - site_description
   - minify:
       minify_html: true
 

mkdocs_mdpo_plugin/config.py

@@ -27,6 +27,7 @@
     ('cross_language_search', Type(bool, default=True)),
     ('min_translated_messages', Type((str, int), default=None)),
     ('exclude', Type(list, default=[])),
+    ('translate', Type(list, default=[])),
 )
 
 
@@ -183,7 +184,7 @@ def _languages_required():
         # if cross_language_search is active, add all languages to 'search'
         # plugin configuration
         lunr_languages = get_lunr_languages()
-        search_langs = config['plugins']['search'].config['lang'] or []
+        search_langs = config['plugins']['search'].config.get('lang', [])
         for language in plugin.config['languages']:
             if language in lunr_languages:
                 if language not in search_langs:
@@ -220,7 +221,7 @@ def _languages_required():
             plugin.config['min_translated_messages'] = min_translated
 
     # check that 'exclude' contains a valid list
-    exclude = plugin.config.get('exclude') or []
+    exclude = plugin.config.get('exclude', [])
     if not isinstance(exclude, list):
         raise ValidationError(
             'Expected mdpo\'s "exclude" setting to be a list, but found'
@@ -236,6 +237,28 @@ def _languages_required():
                 )
     plugin.config['exclude'] = exclude
 
+    # translation of configuration settings
+    valid_translate_settings = ['site_name', 'site_description']
+    for setting in plugin.config.get('translate', []):
+        if setting not in valid_translate_settings:
+            valid_translate_settings_readable = ' and '.join([
+                f"'{opt}'" for opt in valid_translate_settings
+            ])
+            raise ValidationError(
+                f"The setting '{setting}' is not supported for"
+                " 'plugins.mdpo.translate' config setting. Valid settings"
+                f' are {valid_translate_settings_readable}',
+            )
+        elif (
+            setting == 'site_description'
+            and not config.get('site_description')
+        ):
+            logger.warn(
+                '[mdpo] "site_description" is configured to be translated'
+                ' but was not defined in mkdocs.yml',
+            )
+            plugin.config['translate'].remove('site_description')
+
     # store reference in plugin to markdown_extensions for later usage
     plugin.extensions.markdown = markdown_extensions
 

mkdocs_mdpo_plugin/mdpo_utils.py

@@ -6,6 +6,7 @@
 
 
 STRIP_COMMAND_REGEX = re.compile(r'[^\\]' + COMMAND_SEARCH_REGEX)
+MDPO_SETTINGS_TAGS = {'mdpo-site_description', 'mdpo-site_name'}
 
 
 def remove_mdpo_commands_preserving_escaped(text):
@@ -28,3 +29,9 @@ def remove_mdpo_commands_preserving_escaped(text):
         '<!-- mdpo',
         text,
     )
+
+
+def remove_mdpo_setting_tags_from_po_entry(entry):
+    for flag in MDPO_SETTINGS_TAGS:
+        while flag in entry.flags:
+            entry.flags.remove(flag)