Voir la source de Initiation au Lua avec Scribunto/Librairie Language

{{Chapitre
  | idfaculté  = informatique
  | précédent  = [[../Librairie HTML/]]
  | suivant    = [[../Librairie Message/]]
  | page_liée  = Exercices/Sur les librairies Scribunto
  | numéro     = 16
  | niveau     = 10
}}
__TOC__
{{Clr}}
== Présentation ==

Les codes des langues sont décrits dans [[mw:Language code|Language code]]. Bon nombre des codes de langue de MediaWiki sont similaires aux [[w:Étiquette d'identification de langues IETF|codes de langue IETF]], mais tous les codes de langue de MediaWiki ne sont pas des codes langue IETF valides ou vice-versa.

Les fonctions documentées comme <code>mw.language.name</code> sont disponibles dans la table globale <code>mw.language</code>. Les fonctions documentées comme <code>mw.language:name</code> sont des méthodes d'un objet Language (voir [[#mw.language.new|<code>mw.language.new</code>]]).

== Fonctions de la librairie language  ==

Les exemples de ce chapitre se trouveront dans le [[Module:Language]]


Nous commencerons par visualiser le contenu de la librairie language grâce au programme suivant :

<syntaxhighlight lang="lua">
local p = {}

function p.visualisation(frame)
	reponse = ""
	for index, objet in pairs(mw.langage) do
		reponse = reponse.."<br>À la clé "..index..", on trouve un objet de type : "..type(objet)
	end
	return reponse
end

return p
</syntaxhighlight>


'''<nowiki>{{#invoke:Language|visualisation}}</nowiki>''' nous donne : {{#invoke:Language|visualisation}}


Nous voyons que nous avons 9 fonctions.


Étudions ces fonctions dans l’ordre où elles sont sorties :


==== mw.language.isValidCode ====

{{...}}

<code style="white-space:nowrap">mw.language.isValidCode( code )</code>

Retourne vrai si une chaîne de code langue est d'une forme valide, qu’il existe ou pas. Ceci inclut les codes qui sont utilisés pour la personnalisation par les espaces de noms MediaWiki.

Le code peut ne correspondre à aucun langage connu.

Un code de langue est valide s'il ne contient pas certains caractères (deux-point, apostrophe simple ou double, barre oblique renversée ou non, crochet, esperluette, ou le caractère NULL de l'ASCII) et est dans ce cas-là autorisé dans un titre de page.


==== mw.language.getFallbacksFor ====

{{...}}

<code style="white-space:nowrap">mw.language.getFallbacksFor( code )</code>

Renvoie une liste des codes de langue de MediaWiki pour le code spécifié.


==== mw.language.isSupportedLanguage ====

{{...}}

<code style="white-space:nowrap">mw.language.isSupportedLanguage( code )</code>

Vérifie si la localisation est disponible dans MediaWiki pour le code de langue indiqué.

Un code de langue est « supporté » si c’est un code « valide » (qui renvoie true via [[#mw.language.isValidCode|<code>mw.language.isValidCode</code>]]), ne contient pas de lettres en majuscule, et a un fichier dans la version courante de MediaWiki.

Il est possible pour un code de langue d’être « supporté » mais pas « reconnu » (c'est-à-dire renvoyant true via [[#mw.language.isKnownLanguageTag|<code>mw.language.isKnownLanguageTag</code>]]). Veuillez noter aussi que certains codes sont « supportés » malgré que [[#mw.language.isValidBuiltInCode|<code>mw.language.isValidBuiltInCode</code>]] renvoie false.


==== mw.language.new ====

{{...}}

<code style="white-space:nowrap">mw.language.new( code )</code><br>
<code style="white-space:nowrap">mw.getLanguage( code )</code>

Crée un nouvel objet Language. Les objets Language n'ont aucune propriété accessible, mais possèdent de nombreuses méthodes qui sont documentées ci-dessous.


==== mw.language.fetchLanguageNames ====

{{...}}

<code style="white-space:nowrap">mw.language.fetchLanguageNames()</code><br>
<code style="white-space:nowrap">mw.language.fetchLanguageNames( inLanguage )</code><br>
<code style="white-space:nowrap">mw.language.fetchLanguageNames( inLanguage, include )</code><br>

Cherche la liste des langues reconnues par MediaWiki, et retourne une table de correspondance nom de langue ↔ code de langue.

Par défaut, le nom de langue retourné est celui dans la langue en question ; renseigner un code de langue pour <code>inLanguage</code> permet de renvoyer tous les noms dans cette langue.

Par défaut, seules les noms de langue connus par MediaWiki sont renvoyés ; renseigner <code>'all'</code> pour <code>include</code> permet le renvoi de toutes les langues disponibles (e.g. depuis [[mw:Extension:CLDR]]), tandis que renseigner <code>'mwfile'</code> permet de renvoyer seulement les langues qui ont des traductions incluses dans le cœur de MediaWiki ou dans des extensions activées. Pour sélectionner explicitement le défaut, il faut renseigner <code>'mw'</code>.


==== mw.language.isValidBuiltInCode ====

{{...}}

<code style="white-space:nowrap">mw.language.isValidBuiltInCode( code )</code>

Retourne vrai si le code de langue est ou pourrait être disponible dans MediaWiki.

Le code peut en effet ne correspondre à aucun langage connu.

Un code de langue est un "valid built-in code" si c’est un code « valide » (c'est-à-dire qu'on obtient true via [[#mw.language.isValidCode|<code>mw.language.isValidCode</code>]]) ; il est constitué dans ce cas-là seulement de lettres du jeu de codage ASCII, de nombres, de traits d'union, et comporte au moins deux caractères.

Notez que certains codes sont « supportés » (c'est-à-dire qu'on obtient true via [[#mw.language.isSupportedLanguage|<code>mw.language.isSupportedLanguage</code>]]) même si la présente fonction renvoie false.


==== mw.language.fetchLanguageName ====

{{...}}

<code style="white-space:nowrap">mw.language.fetchLanguageName( code, inLanguage )</code>

Le nom complet de la langue du code indiqué : par défaut dans la langue du wiki (autonyme), ou traduit dans la langue indiquée dans <code>inLanguage</code>.


==== mw.language.isKnownLanguageTag ====

{{...}}

<code style="white-space:nowrap">mw.language.isKnownLanguageTag( code )</code>

Retourne vrai si le code indiqué est un code reconnu par MediaWiki.

Un code de langue est « connu » si c’est un « ''valid built-in code'' » (c'est-à-dire qui renvoie true via [[#mw.language.isValidBuiltInCode|<code>mw.language.isValidBuiltInCode</code>]]) et renvoie une chaîne non vide via [[#mw.language.fetchLanguageName|<code>mw.language.fetchLanguageName</code>]].

==== mw.language.getContentLanguage ====

{{...}}

<code>mw.language.getContentLanguage()</code><br>
<code>mw.getContentLanguage()</code>

Retourne un nouvel objet Language correspondant à la langue du wiki sur lequel on se trouve.


== Méthode de la librairie Langage  ==

Nous commencerons par visualiser le contenu d'un objet Langage grâce au programme suivant :

<syntaxhighlight lang="lua">
local p = {}

function p.visualise(frame)
	reponse = ""
	langage = mw.language.new("essai")
	for index, objet in pairs(langage) do
		reponse = reponse.."<br>À la clé "..index..", on trouve un objet de type : "..type(objet)
	end
	return reponse
end

return p
</syntaxhighlight>


'''<nowiki>{{#invoke:Language|visualise}}</nowiki>''' nous donne : {{#invoke:Language|visualise}}


Nous voyons qu’il y a 22 méthodes et une chaîne de caractère.


Débarrassons nous de la chaîne de caractères

==== langage.code ====

{{...}}


Étudions maintenant les 22 méthodes dans l’ordre où elles sont sorties :

==== mw.language:convertGrammar ====

{{...}}

<code style="white-space:nowrap">lang:convertGrammar( word, case )</code><br>
<code style="white-space:nowrap">lang:grammar( case, word )</code>

: ''Notez l’ordre différent des paramètres dans les deux versions. <code>convertGrammar</code> utilise le même ordre des paramètres que la méthode de même nom dans l’objet Language alors que <code>grammar</code> utilise le même ordre des paramètres que la parser-function de même nom (voir [[mw:Help:Magic words#Localisation]]).''

Permet de choisir la forme correcte de <code>word</code> pour l'inflexion <code>case</code>.

Les valeurs possibles pour <code>word</code> et <code>case</code> dépendent de la langue, voir [[m:Help:Magic words#Language-dependent word conversions]] et [[translatewiki:Grammar]] pour plus de détails.


==== mw.language:isRTL ====

{{...}}

<code style="white-space:nowrap">lang:isRTL()</code>

Retourne vrai si la langue est écrite de droite à gauche, faux si elle est écrite de gauche à droite.


==== mw.language:getArrow ====

{{...}}

<code style="white-space:nowrap">lang:getArrow( direction )</code>

Retourne un caractère Unicode correspondant à la direction <code>direction</code>:
* '''forwards''': "→" ou "←" selon l'orientation de la langue
* '''backwards''': "←" ou "→" selon l'orientation de la langue
* '''left''': "←"
* '''right''': "→"
* '''up''': "↑"
* '''down''': "↓"


==== mw.language:parseFormattedNumber ====

{{...}}

<code style="white-space:nowrap">lang:parseFormattedNumber( s )</code>

Prend un nombre formaté par [[#mw.language:formatNum|lang:formatNum()]] et retourne le nombre correspondant. C'est une version « compatible avec les conventions de la langue » de [[#tonumber|<code>tonumber()</code>]].


==== mw.language:getDirMarkEntity ====

{{...}}

<code style="white-space:nowrap">lang:getDirMarkEntity( opposite )</code>

Retourne "&amp;lrm;" ou "&amp;rlm;", selon la direction de la langue et selon que <code>opposite</code> est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).


==== mw.language:getDirMark ====

{{...}}

<code style="white-space:nowrap">lang:getDirMark( opposite )</code>

Retourne une chaîne contenant soit U+200E (le symbole d'écriture de gauche à droite) soit U+200F (le symbole de l'écriture de droite à gauche), selon la direction de la langue et selon que <code>opposite</code> est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).


==== mw.language:getFallbackLanguages ====

{{...}}

<code style="white-space:nowrap">lang:getFallbackLanguages()</code>

Renvoie une liste de codes de langue de MediaWiki pour cet objet langue. Équivalent à <code style="white-space:nowrap">mw.language.getFallbacksFor( lang:getCode() )</code>.


==== mw.language:ucfirst ====

{{...}}

<code style="white-space:nowrap">lang:ucfirst( s )</code>

Convertit le premier caractère de la chaîne en majuscule, comme le fait [[#mw.language:uc|lang:uc()]].


==== mw.language:getDir ====

{{...}}

<code style="white-space:nowrap">lang:getDir()</code>

Retourne "ltr" (left-to-right → de gauche à droite) ou "rtl" (right-to-left → de droite à gauche), selon la direction de la langue.


==== mw.language:caseFold ====

{{...}}

<code style="white-space:nowrap">lang:caseFold( s )</code>

Convertit la chaîne en une forme appropriée pour une comparaison non sensible à la casse. Notez que le résultat peut ne pas avoir de sens s'il est affiché.


==== mw.language:grammar ====

{{...}}


==== mw.language:lc ====

{{...}}

<code style="white-space:nowrap">lang:lc( s )</code>

Convertit la chaîne en minuscules, en respectant les règles particulières de la langue correspondante.

Quand la [[Initiation au Lua avec Scribunto/Chaînes de caractères#La librairie Ustring|librairie Ustring]] est chargée, la fonction [[Initiation au Lua avec Scribunto/Chaînes de caractères#La librairie Ustring|mw.ustring.lower()]] est codée en appelant <code style="white-space:nowrap">mw.language.getContentLanguage():lc( s )</code>.


==== mw.language:plural ====

{{...}}


==== mw.language:gender ====

{{...}}

<code style="white-space:nowrap">lang:gender( what, masculine, feminine, neutral )</code><br>
<code style="white-space:nowrap">lang:gender( what, { masculine, feminine, neutral } )</code>

Permet de choisir la chaîne correspondante au genre indiqué par <code>what</code>, qui peut être "male", "female" ou un nom d'utilisateur.


==== mw.language:lcfirst ====

{{...}}

<code style="white-space:nowrap">lang:lcfirst( s )</code>

Convertit le premier caractère de la chaîne en minuscule, comme le fait [[#mw.language:lc|lang:lc()]].


==== mw.language:formatNum ====

{{...}}

<code style="white-space:nowrap">lang:formatNum( n )</code>

Formate un nombre en respectant le groupement des chiffres et le séparateur décimal de la langue correspondante. Par exemple, « 123456.78 » produira « 123,456.78 », « 123.456,78 », ou même « ١٢٣٬٤٥٦٫٧٨ » selon la langue du wiki.


==== mw.language:formatDate ====

{{...}}

<code style="white-space:nowrap">lang:formatDate( format, timestamp, local )</code>

Formate une date selon le format indiqué dans la chaîne ''format''. Si <code>timestamp</code> est omis, l’heure actuelle est utilisée. La valeur <code>local</code> doit être un booléen ou ''nil''. Si local est vrai, l’heure est formatée à partir de [[mw:Manual:$wgLocaltimezone|l’heure locale du wiki]] plutôt qu’à partir de l’heure UTC.

La chaîne de formatage et les valeurs supportées pour <code>timestamp</code> sont identiques à celles du [[mw:Help:Extension:ParserFunctions#.23time|parser function #time]]. Notez que les antislash ("\") peuvent nécessiter d’être doublés en Lua alors que ce n’est pas nécessaire en wikitexte (car ce caractère a un sens particulier en Lua et non en wikitexte) :

 -- ceci génère un retour à la ligne alors que <nowiki>{{#time:\n}}</nowiki> affiche un "n" ({{#time:\n}})
 lang:formatDate( '\n' )
 
 -- ceci affiche un "n" alors que <nowiki>{{#time:\\n}}</nowiki> affiche un "\"
 -- suivi du numéro du mois. ({{#time:\\n}})
 lang:formatDate( '\\n' )
 
 -- ceci affiche un "\" suivi du numéro du mois, alors que <nowiki>{{#time:\\\\n}}</nowiki>
 -- affiche deux "\" suivi du numéro du mois. ({{#time:\\\\n}})
 lang:formatDate( '\\\\n' )


==== mw.language:getCode ====

{{...}}

<code style="white-space:nowrap">lang:getCode()</code>

Retourne le code de langue correspondant à cet objet.


==== mw.language:formatDuration ====

{{...}}

<code style="white-space:nowrap">lang:formatDuration( seconds )</code><br>
<code style="white-space:nowrap">lang:formatDuration( seconds, allowedIntervals )</code>

Découpe une durée (exprimée en secondes) dans des unités utilisables par l'homme, par exemple : 12345 en 3 heures, 25 minutes et 45 secondes, retournant le résultat dans une chaîne.

<code>allowedIntervals</code>, si indiqué, est une table avec des valeurs nommant les unités d'intervalle à utiliser dans la réponse. Cela comprend : 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', et 'seconds'.


==== mw.language:uc ====

{{...}}

<code style="white-space:nowrap">lang:uc( s )</code>

Convertit la chaîne en majuscules, en respectant les règles particulières de la langue correspondante.

Quand la [[Initiation au Lua avec Scribunto/Chaînes de caractères#La librairie Ustring|librairie Ustring]] est chargée, la fonction [[Initiation au Lua avec Scribunto/Chaînes de caractères#La librairie Ustring|mw.ustring.upper()]] est codée en appelant <code style="white-space:nowrap">mw.language.getContentLanguage():uc( s )</code>.


==== mw.language:convertPlural ====

{{...}}

<code style="white-space:nowrap">lang:convertPlural( n, ... )</code><br>
<code style="white-space:nowrap">lang:convertPlural( n, forms )</code><br>
<code style="white-space:nowrap">lang:plural( n, ... )</code><br>
<code style="white-space:nowrap">lang:plural( n, forms )</code>

Permet de choisir la forme gramaticale adaptée depuis <code>forms</code> (qui doit être une [[Initiation au Lua avec Scribunto/Tables et fonctions#Définition élémentaire d'une table|séquence]]) ou <code>...</code> en se basant sur le nombre <code>n</code>. Par exemple en anglais, vous pouvez utiliser <code style="white-space:nowrap">n .. ' ' .. lang:plural( n, 'sock', 'socks' )</code> ou <code style="white-space:nowrap">n .. ' ' .. lang:plural( n, { 'sock', 'socks' } )</code> pour générer un texte grammaticalement correct qu’il y ait 1 ou 200 "socks".

Le nombre de valeurs nécessaires pour la séquence dépend de la langue ; voir [[m:Help:Magic words#Language-dependent word conversions]] et [[translatewiki:FAQ#PLURAL]] pour plus de détails.


==== mw.language:getDurationIntervals ====

{{...}}

<code style="white-space:nowrap">lang:getDurationIntervals( seconds )</code><br>
<code style="white-space:nowrap">lang:getDurationIntervals( seconds, allowedIntervals )</code>

Découpe une durée exprimée en secondes en unités lisibles par l'homme, et retourne le résultat dans une table dont les éléments sont classés par unité. Par exemple 12345 retournera les éléments 3 heures, 25 minutes et 45 secondes.

<code>allowedIntervals</code>, si précisé, est une table avec comme valeurs les noms des unités à utiliser : 'millennia', 'centuries', 'decades', 'years', 'days', 'hours', 'minutes', and 'seconds'.


{{Bas de page
  | idfaculté  = informatique
  | précédent  = [[../Librairie HTML/]]
  | suivant    = [[../Librairie Message/]]
}}