Merge ff2ad27 into 384de32

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.21
+current_version = 0.0.22
 
 [bumpversion:file:mkdocs_mdpo_plugin/__init__.py]
 

.pre-commit-config.yaml

@@ -64,6 +64,7 @@ repos:
     rev: v1.7.0
     hooks:
       - id: untranslated-messages
+        exclude: file-excluded-from-translations\.md\.po
       - id: obsolete-messages
       - id: fuzzy-messages
       - id: remove-metadata

docs/locale/es/config.md.po

@@ -204,5 +204,23 @@ msgid ""
 "builtin Mkdocs search plugin."
 msgstr ""
 "El soporte de esta característica actualmente incluye el tema [mkdocs-"
-"material], el tema por defecto de Mkdocs, el tema de Readthedocs y todos los "
-"temas que usen el plugin de búsqueda incluido en Mkdocs."
+"material], el tema por defecto de Mkdocs, el tema de Readthedocs y todos los"
+" temas que usen el plugin de búsqueda incluido en Mkdocs."
+
+msgid ""
+"Minimum number or percentage of messages in all files to include the "
+"translated pages for a language. An information message will be displayed if"
+" a language does not reach the minimum translation requirements."
+msgstr ""
+"Número o porcentaje de mensajes mínimo en todos los archivos para incluir "
+"las páginas traducidas para un idioma. Un mensaje de información será "
+"mostrado si un idioma no alcanza los requisitos de traducción mínimos."
+
+msgid ""
+"Specify as a string ending with `%` like `\"55%\"` for percentages of total "
+"messages or as an integer like `76` to determine the minimum number of "
+"translated messages required to include a language."
+msgstr ""
+"Especifica como cadena terminada con `%` como `\"55%\"` para porcentaje de "
+"mensajes totales o como entero como `76` para determinar el número mínimo de"
+" mensajes traducidos requeridos para incluir un idioma."

docs/src/config.md

@@ -191,6 +191,28 @@ The context for the template includes:
 
 ## Content
 
+<!-- mdpo-disable-next-line -->
+### **`cross_language_search`** (*bool*)
+
+It configures if the search plugin of the theme will search through all
+languages. By default is enabled. You can disable it to restrict the search
+to the active language.
+
+The support for this feature currently includes the [mkdocs-material] theme,
+the Mkdocs theme, the Readthedocs theme and all themes which use the builtin
+Mkdocs search plugin.
+
+<!-- mdpo-disable-next-line -->
+### **`min_translated_messages`** (*str* or *int*)
+
+Minimum number or percentage of messages in all files to include the
+translated pages for a language. An information message will be displayed
+if a language does not reach the minimum translation requirements.
+
+Specify as a string ending with `%` like `"55%"` for percentages of
+total messages or as an integer like `76` to determine the minimum
+number of translated messages required to include a language.
+
 <!-- mdpo-disable-next-line -->
 ### **`ignore_extensions`** (*list*)
 
@@ -203,16 +225,6 @@ File extensions that are ignored from being added to site directory, defaults to
 You can ignore certain messages from being dumped into PO files adding them to
 this list.
 
-<!-- mdpo-disable-next-line -->
-### **`cross_language_search`** (*bool*)
-
-It configures if the search plugin of the theme will search through all
-languages. By default is enabled. You can disable it to restrict the search to the active language.
-
-The support for this feature currently includes the [mkdocs-material] theme,
-the Mkdocs theme, the Readthedocs theme and all themes which use the builtin
-Mkdocs search plugin.
-
 [iso-369]: https://en.wikipedia.org/wiki/ISO_639
 [mkdocs-material]: https://squidfunk.github.io/mkdocs-material
 [mkdocs-material-site-language]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language

examples/min-translated-messages/docs/locale/es/file-excluded-from-translations.md.po

@@ -0,0 +1,12 @@
+#
+msgid ""
+msgstr ""
+
+msgid "File excluded from translations"
+msgstr ""
+
+msgid "Excluded header"
+msgstr "Encabezado excluido"
+
+msgid "Excluded content"
+msgstr ""

examples/min-translated-messages/docs/locale/es/index.md.po

@@ -0,0 +1,12 @@
+#
+msgid ""
+msgstr ""
+
+msgid "Home"
+msgstr "Inicio"
+
+msgid "Welcome to MkDocs"
+msgstr "Bienvenido a Mkdocs"
+
+msgid "Some content"
+msgstr "Algo de contenido"

examples/min-translated-messages/docs/locale/fr/file-excluded-from-translations.md.po

@@ -0,0 +1,12 @@
+#
+msgid ""
+msgstr ""
+
+msgid "File excluded from translations"
+msgstr ""
+
+msgid "Excluded header"
+msgstr ""
+
+msgid "Excluded content"
+msgstr ""

examples/min-translated-messages/docs/locale/fr/index.md.po

@@ -0,0 +1,12 @@
+#
+msgid ""
+msgstr ""
+
+msgid "Home"
+msgstr "Accueil"
+
+msgid "Welcome to MkDocs"
+msgstr "Bienvenue sur mkdocs"
+
+msgid "Some content"
+msgstr "Du contenu"

examples/min-translated-messages/docs/src/file-excluded-from-translations.md

@@ -0,0 +1,3 @@
+# Excluded header
+
+Excluded content

examples/min-translated-messages/docs/src/index.md

@@ -0,0 +1,3 @@
+# Welcome to MkDocs
+
+Some content

examples/min-translated-messages/mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: mkdocs-mdpo-plugin 'min_translated_messages' example
+site_url: https://mkdocs-mdpo.ga
+docs_dir: docs/src
+
+nav:
+  - Home: index.md
+  - File excluded from translations: file-excluded-from-translations.md
+
+plugins:
+  - search
+  - mdpo:
+      languages:
+        - en
+        - es
+        - fr
+      cross_language_search: false
+      locale_dir: ../locale
+      min_translated_messages: 55%

mkdocs_mdpo_plugin/__init__.py

@@ -1,3 +1,3 @@
 """mkdocs-mdpo-plugin package"""
 
-__version__ = '0.0.21'
+__version__ = '0.0.22'

mkdocs_mdpo_plugin/config.py

@@ -20,6 +20,7 @@
     ('ignore_extensions', Type(list, default=['.po', '.pot', '.mo'])),
     ('ignore_msgids', Type(list, default=[])),
     ('cross_language_search', Type(bool, default=True)),
+    ('min_translated_messages', Type((str, int), default=None)),
 )
 
 
@@ -71,6 +72,17 @@ def _languages_required():
             plugin.config['languages'] = [alt['lang'] for alt in alternate]
         else:
             raise _languages_required()
+    else:
+        if not isinstance(languages, list):
+            raise ValidationError(
+                'Expected "languages" config setting to be a list',
+            )
+        for i, language in enumerate(languages):
+            if not isinstance(language, str):
+                raise ValidationError(
+                    f'Expected "languages[{i}]" config setting to'
+                    f' be a string but is {language}',
+                )
 
     default_language = plugin.config.get('default_language')
     if not default_language:
@@ -149,11 +161,35 @@ def _languages_required():
 
     # check that cross language search configuration is valid
     if plugin.config.get('cross_language_search') is False:
+        plugin_names = [p for p in config['plugins']]
         if 'search' not in config['plugins']:
             raise ValidationError(
                 '"cross_language_search" setting is disabled but'
                 ' no "search" plugin has been added to "plugins"',
             )
+        elif plugin_names.index('search') > plugin_names.index('mdpo'):
+            raise ValidationError(
+                '"search" plugin must be placed before "mdpo"'
+                ' plugin if you want to disable "cross_language_search".',
+            )
+
+    # check that minimum translated messages required for each language
+    # is a valid value
+    min_translated = plugin.config.get('min_translated_messages')
+    if min_translated is not None:
+        try:
+            if '%' in str(min_translated):
+                min_translated = -float(min_translated.strip('%'))
+            else:
+                min_translated = int(min_translated)
+        except Exception:
+            raise ValidationError(
+                f"The value '{min_translated}' for"
+                " 'min_translated_messages' config setting"
+                '  is not a valid percentage or number.',
+            )
+        else:
+            plugin.config['min_translated_messages'] = min_translated
 
     # store reference in plugin to markdown_extensions for later usage
     plugin.extensions.markdown = markdown_extensions

mkdocs_mdpo_plugin/plugin.py

@@ -1,6 +1,7 @@
 """mkdocs-mdpo-plugin module"""
 
 import functools
+import logging
 import math
 import os
 import sys
@@ -11,7 +12,6 @@
 from mdpo.md2po import Md2Po
 from mdpo.po2md import Po2Md
 
-from mkdocs_mdpo_plugin.compat import removesuffix
 from mkdocs_mdpo_plugin.config import CONFIG_SCHEME, on_config_event
 from mkdocs_mdpo_plugin.extensions import Extensions
 from mkdocs_mdpo_plugin.mdpo_events import (
@@ -27,6 +27,15 @@
 )
 from mkdocs_mdpo_plugin.search_indexes import TranslationsSearchPatcher
 from mkdocs_mdpo_plugin.translations import Translation, Translations
+from mkdocs_mdpo_plugin.utils import (
+    po_messages_stats,
+    readable_float,
+    removesuffix,
+)
+
+
+# use Mkdocs build logger
+logger = logging.getLogger('mkdocs.commands.build')
 
 
 class MdpoPlugin(mkdocs.plugins.BasePlugin):
@@ -162,7 +171,12 @@ def _translate_nav_section(items):
                     if item.children:
                         _translate_nav_section(item.children)
 
-                if item.title not in self.translations.nav:
+                if (
+                    item.title not in self.translations.nav or
+                    language not in self.translations.nav[item.title]
+                ):
+                    # language not added because page has been excluded
+                    # from translations
                     continue
 
                 tr_title, tr_url = self.translations.nav[
@@ -282,9 +296,26 @@ def on_page_markdown(self, markdown, page, config, files):
             for entry in compendium_pofile:
                 if entry not in po and entry.msgstr:
                     po.append(entry)
-
             po.save(po_filepath)
 
+            # if a minimum number of translations are required to include
+            # the file, compute number of untranslated messages
+            min_translated = self.config['min_translated_messages']
+            if min_translated:
+                n_translated, n_total = po_messages_stats(str(po))
+                if language not in self.translations.stats:
+                    self.translations.stats[language] = {
+                        'total': n_total,
+                        'translated': n_translated,
+                    }
+                else:
+                    self.translations.stats[language][
+                        'total'
+                    ] += n_total
+                    self.translations.stats[language][
+                        'translated'
+                    ] += n_translated
+
             # translate part of the markdown producing a translated file
             # content (the rest of the translations are handled by extensions,
             # see `extension` module)
@@ -376,6 +407,47 @@ def on_page_markdown(self, markdown, page, config, files):
 
     def on_post_page(self, output, page, config):
         if hasattr(page.file, '_mdpo_language'):
+            # if the language should be included from the build, ignore it
+            min_translated = self.config['min_translated_messages']
+            if min_translated:
+                language = page.file._mdpo_language
+                stats = self.translations.stats[language]
+                if abs(min_translated) != min_translated:
+                    min_translated = abs(min_translated)
+                    if 'percent_translated' in stats:
+                        percent_translated = stats['percent_translated']
+                    else:
+                        percent_translated = (
+                            stats['translated'] / stats['total'] * 100
+                        )
+                        stats['percent_translated'] = percent_translated
+                    if percent_translated < min_translated:
+                        if language in self.config['languages']:
+                            logger.info(
+                                '[mdpo] '
+                                f'Excluding language "{language}". Translated'
+                                f' {readable_float(percent_translated)}%'
+                                f' ({stats["translated"]} of'
+                                f' {stats["total"]} messages) but'
+                                f' required {readable_float(min_translated)}%'
+                                ' at least.\n',
+                            )
+                            self.config['languages'].remove(language)
+                        return
+                else:
+                    if stats['translated'] < min_translated:
+                        if language in self.config['languages']:
+                            logger.info(
+                                '[mdpo] '
+                                f'Excluding language "{language}".'
+                                f' Translated {stats["translated"]} messages'
+                                f' of {stats["total"]} but required'
+                                f' {min_translated} translated'
+                                ' messages at least.\n',
+                            )
+                            self.config['languages'].remove(language)
+                        return
+
             # write translated HTML file to 'site' directory
             os.makedirs(
                 os.path.join(
@@ -505,8 +577,8 @@ def on_serve(self, *args, **kwargs):  # pragma: no cover
         directory.
         """
         if '..' not in self.config['locale_dir']:
-            sys.stderr.write(
-                'ERROR [mdpo] -  '
+            logger.error(
+                '[mdpo] -  '
                 "You need to set 'locale_dir' configuration setting"
                 ' pointing to a directory placed outside'
                 " the documentation directory ('docs_dir') in order to"

mkdocs_mdpo_plugin/search_indexes.py

@@ -10,16 +10,16 @@
    The files are named 'search_index_es.json', 'search_index_fr.json'...
 3. Patch the JS files which loads the 'search_index.json' file creating
    one for each language. This depends completely on the active theme.
-4. Patch HTML files to load these language versions of JS files instead
-   of the original ones.
+4. Patch HTML page files to load these language versions of JS files
+   instead of the original ones.
 5. Additionally, for themes like readthedocs, patchs HTML search files.
 """
 
 import copy
 import json
 import os
 
-from mkdocs_mdpo_plugin.compat import removesuffix
+from mkdocs_mdpo_plugin.utils import removesuffix
 
 
 def _language_extension_path(path, extension, language, separator='_'):