Skip to content

Commit

Permalink
Update parentlangbehaviour description
Browse files Browse the repository at this point in the history 
Using the base English text proposed by @michael-milette.

Also use the same description for the README file.

[Re: #42]
  • Loading branch information
@iarenaza
iarenaza committed Nov 26, 2024
1 parent cfad429 commit 032d8c2
Show file tree
Hide file tree
Showing 4 changed files with 217 additions and 111 deletions.
20 changes: 12 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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":
Expand Down
97 changes: 66 additions & 31 deletions lang/en/filter_multilang2.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'] = '<p>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 <em>parent languages
behaviour</em>:</p>
<ul>
<li><b>Always use parent languages, excluding \'en\'</b>. <em>This is
the traditional behaviour of the plugin</em>, 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 <em>explicitly</em>
specified in the language blocks (e.g., <small><tt>{mlang en}This text will
be shown when the current language used by the user displaying the
content is \'en\'{mlang})</tt></small>.</li>
<li><b>Always use parent languages, including \'en\'</b>. 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 <em>will be</em> displayed if the current language used
by the user displaying the content is \'en\'.</li>
<li><b>Never use parent languages</b>. 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.</li> </ul>';
$string['parentlangbehaviour_desc'] = '
<p>
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 "<em>parent languages behaviour</em>":
</p>
<ol>
<li>
<b>Always use parent languages, excluding \'en\'.</b>
<ul>
<li>
This is the default setting. The filter considers the
languages listed in the language block\'s <code>{mlang
...}</code> tag, and all of their parent languages (up to,
but not including, the root <code>en</code> language).
</li>
<li>
Example: If a language block specifies <code>{mlang
en_us_k12}</code>, it will only display if the user\'s
current language is <code>en_us_k12</code>
or <code>en_us</code> but not <code>en</code>.
</li>
<li>
Note: English can still be used explicitly in the language
block. For example, <code>{mlang en}This text will be shown
when the user’s current language is \'en\'.{mlang}</code>
will display the content when the user\'s current language
is <code>en</code>.
</li>
</ul>
</li>
<li>
<b>Always use parent languages, including \'en\'.</b>
<ul>
<li>
This setting works like the previous one, but includes the
root <code>en</code> as a valid parent language.
</li>
<li>
Example: If a language block specifies <code>{mlang
en}</code>, it will display if the user\'s current language
is either <code>en_us_k12</code>,
<code>en_us</code> or <code>en</code>.
</li>
</ul>
</li>
<li>
<b>Never use parent languages.</b>
<ul>
<li>
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.
</li>
<li>
Example: If a language block specifies <code>{mlang
en_us_k12}</code>, it will only display if the user\'s
current language is <code>en_us_k12</code>,
not <code>en_us</code>
or <code>en</code>.
</li>
</ul>
</li>
</ol>';
$string['parentlangdefault'] = 'Always use parent languages, excluding \'en\' (traditional behaviour).';
$string['parentlangnever'] = 'Never use parent languages.';
$string['pluginname'] = 'Multi-Language Content (v2) Filter';
Expand Down
104 changes: 69 additions & 35 deletions lang/es/filter_multilang2.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'] = '<p>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
<em>comportamiento de idiomas padre</em>:</p>
<ul>
<li><b>Usar idiomas padre siempre, excluído \'en\'</b>. <em>Este es el
comportamiento tradicional del plugin</em>, y es el valor
predeterminado para el ajuste. Cuando se selecciona este
comportamiento, el filtro usa tanto los idiomas especificados en el
bloque, como los idiomas padre de éstos (de forma recursiva hasta la
cima), para emparejar el idioma actual utilizado por el usuario que
está visualizando el contenido. Pero el idioma Inglés (\'en\') nunca
se considera un idioma padre en este caso, y se elimina de la lista de
idiomas padre. Por ejemplo, si un bloque de idioma especifica
\'en_kids\' en su lista de idiomas, entonces dicho bloque <em>no</em>
se mostrará si el idioma actual del usuario que visualiza el contenido
es \'en\'. Nótese que el filtro sí usará el idioma Inglés si éste se
especifica <em>explícitamente</em> en el bloque de idioma (p.ej.,
<small><tt>{mlang en}Este texto sí se mostrará si el idioma actual del
usuario que visualiza el contenido es
\'en\'{mlang}</tt></small>).</li>
<li><b>Usar idiomas padre siempre, incluído \'en\'</b>. Este
comportamiento funciona como "Usar idiomas padre siempre, excluído
\'en\'", pero no elimina el idioma Inglés (\'en\') de la lista de
idiomas padre. Así por ejemplo, si un bloque de idioma especifica
\'en_kids\' en su lista de idiomas, entonces dicho bloque <em>sí</em>
se mostrará si el idioma actual del usuario que visualiza el contenido
es \'en\'.</li>
<li><b>No usar idiomas padre nunca</b>. Como su nombre indica, este
comportamiento nunca usa los idiomas padre para emparejar el idioma
actual utilizado por el usuario que está visualizando el contenido. El
filtro se limita a usar únicamente los idiomas especificados en el
bloque de idioma.</li> </ul>';
$string['parentlangbehaviour_desc'] = '
<p>
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 <em>comportamiento de
idiomas padre</em>:
</p>
<ol>
<li>
<b>Usar idiomas padre siempre, excluído \'en\'</b>.
<ul>
<li>
Este es el valor predeterminado para el ajuste. El filtro
tiene en cuenta los idiomas indicados en la etiqueta del
bloque de idioma <code>{mlang ...}</code>, así como todos sus
idiomas padres (hasta, pero sin includir, el idioma
raíz <code>en</code>).
</li>
<li>
Ejemplo: si un bloque de idioma especifica <code>{mlang
en_us_k12}...{mlang}</code>, dicho bloque sólo se visualizará
si el idioma del usuario es <code>en_us_k12</code>
o <code>en_us</code>, pero no si se trata de <code>en</code>.
</li>
<li>
Nota: Siempre es posible usar el idioma Inglés
(<code>en</code>), si éste se indica explícitamente en el
bloque de idioma. Por ejemplo, el bloque de
idioma <code>{mlang en}This text will be shown when the user’s
current language is \'en\'.{mlang}</code> se mostrará cuando
el idioma del usuario sea <code>en</code>.
</li>
</ul>
</li>
<li>
<b>Usar idiomas padre siempre, incluído \'en\'.</b>
<ul>
<li>
Este ajuste funciona como el anterior, pero incluye la
raíz <code>en</code> como idioma padre válido.
</li>
<li>
Ejemplo: si un bloque de idioma especifica <code>{mlang
en}...{mlang}</code>, dicho bloque se visualizará tanto si el
idioma del usuario es <code>en_us_k12</code>, como si
es <code>en_us</code>, o si es <code>en</code>.
</li>
</ul>
</li>
<li>
<b>No usar idiomas padre nunca.</b>
<ul>
<li>
Como su nombre indica, no se usan los idiomas padre nunca.
El filtro sólo considera los idiomas indicados de forma
explícita en el bloque de idioma, y no considera en ningún
caso ningún idioma padre.
</li>
<li>
Ejemplo: si un bloque de idioma especifica <code> {mlang
en_us_k12}...{mlang}</code>, dicho bloque sólo se visualizará
si el idioma del usuario es <code>en_us_k12</code>, pero no si
es <code>en_us</code> o <code>en</code>.
</li>
</ul>
</li>
</ol>';
$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)';
Expand Down
107 changes: 70 additions & 37 deletions lang/fr/filter_multilang2.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'] = '<p>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 <em>comportement des langues parentes</em>:</p>
<ul>
<li><b>Utiliser toujours les langues parentes, à l\'exclusion de
\'en\'</b>. <em>Il s\'agit du comportement
traditionnel du plugin</em> et constitue la valeur par défaut du
paramètre. Lorsque ce comportement est sélectionné, le filtre utilise
à la fois les langues spécifiées dans le bloc de langue et tous les
parents de ces langues (de manière récursive vers le haut), pour
correspondre à la langue actuellement utilisée par
l\'utilisateur. Mais la langue anglaise (\'en\') n\'est jamais
considérée comme une langue parente dans ce cas et est supprimée de la
liste des langues parentes. Par exemple, un bloc de langue qui
spécifie \'en_kids\' dans la liste des langues <em>ne sera pas</em>
affiché si la langue actuellement utilisée par l\'utilisateur
affichant le contenu est \'en\'. Notez que la langue anglaise est
toujours utilisée par le filtre si elle est explicitement spécifiée
dans le bloc de langue (p.ex., <small><tt>{mlang en}Ce texte ci sera
affiché si la langue actuellement utilisée par l\'utilisateur
affichant le contenu est \'en\'{mlang}</tt></small>).</li>
<li><b>Utiliser toujours les langues parentes, y compris
\'en\'</b>. Ce comportement fonctionne comme "Utiliser toujours les
langues parentes, à l\'exclusion de \'en\'", mais ne supprime pas la
langue anglaise (\'en\') de la liste des langues parentes. Par
exemple, un bloc de langue qui spécifie \'en_kids\' dans la liste des
langues <em>sera</em> affiché si la langue actuellement utilisée par
l\'utilisateur affichant le contenu est \'en\'.</li>
<li><b>N\'utiliser jamais les langues parentes</b>. Comme son nom
l\'indique, les langues parents ne sont jamais utilisées pour
correspondre à la langue actuellement utilisée par l\'utilisateur
affichant le contenu. Le filtre se limite aux langues spécifiées
dans le bloc de langue.</li>
</ul>';
$string['parentlangbehaviour_desc'] = '
<p>
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 <em>comportement des
langues parentes</em>:
</p>
<ol>
<li>
<b>Utiliser toujours les langues parentes, à l\'exclusion de \'en\'</b>.
<ul>
<li>
Il s\'agit de la valeur par défaut du paramètre. Le filtre
utilise à la fois les langues specifiées dans le bloc de
langue <code>{mlang ...}</code>, ainsi que tous ses langues
parentes (jusqu\'à, mais sans inclure, la langue
racine <code>en</code>).
</li>
<li>
Exemple: Si un bloc de langue spécifie <code>{mlang
en_us_k12}...{mlang}</code>, ce bloc sera uniquement affiché
si la langue de l\'utilisateur est <code>en_us_k12</code>
ou <code>en_us</code>, mais pas s\'il s\'agit
de <code>en</code>.
</li>
<li>
Remarque: Il est toujours possible d\'utiliser la langue
anglaise (<code>en</code>), si cela est explicitement indiquée
dans le bloc de langue. Par exemple, le bloc de
langue <code>{mlang en}This text will be shown when the user’s
current language is \'en\'.{mlang}</code> s\'affichera lorsque
la langue de l\'utilisateur est <code>en</code>.
</li>
</ul>
</li>
<li>
<b>Utiliser toujours les langues parentes, y compris \'en\'</b>.
<ul>
<li>
Ce paramètre fonctionne comme le précédent, mais inclut la
racine <code>en</code> comme une langue parente valide.
</li>
<li>
Exemple: Si un bloc de langue spécifie <code>{mlang
en}...{mlang}</code>, ce bloc sera affiché si la langue de
l\'utilisateur est <code>en_us_k12</code>, comme si elle
est <code>en_us</code>, ou si elle est <code>en</code>.
</li>
</ul>
</li>
<li>
<b>N\'utiliser jamais les langues parentes</b>.
<ul>
<li>
Comme son nom l\'indique, les langues parentes ne sont jamais
utilisées. Le filtre ne prend en compte que les langues
indiquées explicitement dans le bloc de langue, sans prendre
en compte aucune langue parente.
</li>
<li>
Exemple: si un bloc de langue spécifie <code> {mlang
en_us_k12}...{mlang}</code>, ce bloc sera affiché uniquement
si la langue de l\'utilisateur est <code>en_us_k12</code>,
mais pas si est <code>en_us</code> ou <code>en</code>.
</li>
</ul>
</li>
</ol>';
$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)';
Expand Down

0 comments on commit 032d8c2

Please sign in to comment.