diff --git a/README.md b/README.md index 064c5e2..47d00aa 100644 --- a/README.md +++ b/README.md @@ -35,16 +35,20 @@ CI](https://github.com/iarenaza/moodle-filter_multilang2/workflows/Moodle%20plug - Text outside of "language blocks" will always be shown. ## Configurable parent languages behaviour ## - Since version 2.0.5, the plugin offers a setting to configure how the filter will behave, with respect to parent languages, when processing a language block. -As described in the previous section, when the filter checks whether a language block has to be displayed or not, it tries to match the languages specified in the block with the current language used by the user displaying the content. This matching can be done in three different ways, that the filter calls _parent languages behaviour_: - -* **Always use parent languages, excluding 'en'**. _This is the traditional behaviour of the plugin_, and is the default value for the setting. When this behaviour is selected, the filter uses both the languages specified in the language block, and all the parents of those languages (recursively to the top), to match the current language used by the user. But the English language ('en') is never considered a parent language in this case, and is removed from the parent list. E.g., a language block that specifies 'en_kids' in the language list _will not_ be displayed if the current language used by the user displaying the content is 'en'. Notice that the English language is still used by the filter if it is _explicitly_ specified in the language blocks (e.g., `{mlang en}This text will be shown when the current language used by the user displaying the content is 'en'{mlang}`). - -* **Always use parent languages, including 'en'**. Which works as **Always use parent languages, excluding 'en'**, but does not remove the English ('en') language from the parent languages list. E.g., a language block that specifies 'en_kids' in the language list _will be_ displayed if the current language used by the user displaying the content is 'en'. - -* **Never use parent languages**. As the name implies, parent languages are never used to match the current language used by the user displaying the content. The filter restricts itself to the languages specified in the language block. +The filter determines whether a language block should be displayed based on the languages specified in the block and the current language being used by the user ("the user's current language"). This matching process can follow three different approaches, known as "_parent languages behaviour_": + +1. **Always use parent languages, excluding 'en'.** + * This is the default setting. The filter considers the languages listed in the language block's {mlang} tag, and all of their parent languages (up to but not including the root 'en' language). + * Example: If a language block specifies '{mlang en_us_k12}', it will only display if the user's current language is 'en_us_k12' or 'en_us' but not 'en'. + * Note: English can still be used explicitly in the language block. For example, {mlang en}This text will be shown when the user’s current language is 'en'.{mlang} will display the content when the user's current language is 'en'. +1. **Always use parent languages, including 'en'.** + * This setting works like the previous one but includes the root 'en' as a valid parent language. + * Example: If a language block specifies '{mlang en}', it will display if the user's current language is either 'en_us_k12', 'en_us' or 'en'. +1. **Never use parent languages.** + * As the name suggests, no parent languages are used. The filter only matches the languages explicitly listed in the language block, without considering any parent languages. + * Example: If a language block specifies '{mlang en_us_k12}', it will only display if the user's current language is 'en_us_k12', not 'en_us' or 'en'. ## Definition of "language block" ## Is any text (including spaces, tabs, linefeeds or return characters) placed between '{mlang XX}' and '{mlang}' markers. You can not only put text inside "language block", but also images, videos or external embedded content. For example, this is a valid "language block": diff --git a/lang/en/filter_multilang2.php b/lang/en/filter_multilang2.php index 9fcac50..1130635 100644 --- a/lang/en/filter_multilang2.php +++ b/lang/en/filter_multilang2.php @@ -28,37 +28,72 @@ $string['filtername'] = 'Multi-Language Content (v2)'; $string['parentlangalwaysen'] = 'Always use parent languages, including \'en\'.'; $string['parentlangbehaviour'] = 'Parent languages behaviour'; -$string['parentlangbehaviour_desc'] = '

When the filter checks whether -a language block has to be displayed or not, it tries to match the -languages specified in the block with the current language used by the -user displaying the content. This matching can be done in three -different ways, that the filter calls parent languages -behaviour:

-'; +$string['parentlangbehaviour_desc'] = ' +

+ The filter determines whether a language block should be displayed + based on the languages specified in the block and the current + language being used by the user ("the user\'s current + language"). This matching process can follow three different + approaches, known as "parent languages behaviour": +

+
    +
  1. + Always use parent languages, excluding \'en\'. + +
    2. +
  2. + Always use parent languages, including \'en\'. + +
    3. +
  3. + Never use parent languages. + +
    4. +
'; $string['parentlangdefault'] = 'Always use parent languages, excluding \'en\' (traditional behaviour).'; $string['parentlangnever'] = 'Never use parent languages.'; $string['pluginname'] = 'Multi-Language Content (v2) Filter'; diff --git a/lang/es/filter_multilang2.php b/lang/es/filter_multilang2.php index 1c1a92f..922d03f 100644 --- a/lang/es/filter_multilang2.php +++ b/lang/es/filter_multilang2.php @@ -28,41 +28,75 @@ $string['filtername'] = 'Contenido Multi-Idioma (v2)'; $string['parentlangalwaysen'] = 'Usar idiomas padre siempre, incluído \'en\'.'; $string['parentlangbehaviour'] = 'Comportamiento de idiomas padre'; -$string['parentlangbehaviour_desc'] = '

Para decidir si debe -visualizar o no un bloque de idioma, el filtro trata de emparejar los -idiomas especificados en dicho bloque con el idioma actual utilizado -por el usuario que está visualizando el contenido. Este emparejamiento -se puede realizar de tres formas diferentes, a las que el filtro llama -comportamiento de idiomas padre:

-'; +$string['parentlangbehaviour_desc'] = ' +

+ El filtro determina si un bloque de idioma se debe visualizar o no + basándose en los idiomas indicados en dicho bloque y en el idioma + actual usado por el usuario (en adelante "el idioma del + usuario"). Este emparejamiento se puede realizar de tres formas + diferentes, a las que el filtro llama comportamiento de + idiomas padre: +

+
    +
  1. + Usar idiomas padre siempre, excluído \'en\'. + +
    2. +
  2. + Usar idiomas padre siempre, incluído \'en\'. + +
    3. +
  3. + No usar idiomas padre nunca. + +
    4. +
'; $string['parentlangdefault'] = 'Usar idiomas padre siempre, excluído \'en\' (comportamiento tradicional).'; $string['parentlangnever'] = 'No usar idiomas padre nunca.'; $string['pluginname'] = 'Filtro Contenido Multi-Idioma (v2)'; diff --git a/lang/fr/filter_multilang2.php b/lang/fr/filter_multilang2.php index 1f4b286..ed6f0d7 100644 --- a/lang/fr/filter_multilang2.php +++ b/lang/fr/filter_multilang2.php @@ -28,43 +28,76 @@ $string['filtername'] = 'Contenu Multilingue (v2)'; $string['parentlangalwaysen'] = 'Utiliser toujours les langues parentes, y compris \'en\'.'; $string['parentlangbehaviour'] = 'Comportement des langues parentes.'; -$string['parentlangbehaviour_desc'] = '

Lorsque le filtre vérifie -si un bloc de langue doit être affiché ou non, il essaie de faire -correspondre les langues spécifiées dans le bloc avec la langue -actuellement utilisée par l\'utilisateur affichant le contenu. Cette -correspondance peut être effectuée de trois manières différentes, que -le filtre appelle comportement des langues parentes:

-'; +$string['parentlangbehaviour_desc'] = ' +

+ Le filtre détermine si un bloc de langue doit être affiché ou non en + fonction des langues indiquées dans ledit bloc et de la langue + langue actuelle utilisée par l\'utilisateur (ci-après «la langue de + l\'utilisateur"). Cette correspondance peut être effectuée de trois + manières différentes, que le filtre appelle comportement des + langues parentes: +

+
    +
  1. + Utiliser toujours les langues parentes, à l\'exclusion de \'en\'. + +
    2. +
  2. + Utiliser toujours les langues parentes, y compris \'en\'. + +
    3. +
  3. + N\'utiliser jamais les langues parentes. + +
    4. +
'; $string['parentlangdefault'] = 'Utiliser toujours les langues parentes, à l\'exclusion de \'en\' (comportement traditionnel).'; $string['parentlangnever'] = 'N\'utiliser jamais les langues parentes.'; $string['pluginname'] = 'Filtre de Contenu Multilingue (v2)';