Manual:Messages API/fr

Les peuvent être utilisés dans le code via la classe Message et ses méthodes associées.



Paramètres des messages
Certains messages ont des paramètres. Ils sont représentés par,  ,  , … dans les  messages textuels (statiques), et remplacés au moment de l'exécution. Les valeurs typiques des paramètres sont des nombres (par exemple 3 dans  « Supprimer 3 versions ? »), ou des noms d'utilisateur (comme Bob dans  « Page modifiée par Bob »), des noms de page, des liens, etc. ou quelques fois d'autres messages. Ils peuvent être d'une complexité exemplaire.

La liste des paramètres définis pour chaque message spécifique est placée dans le fichier spécial qqq.json situé dans le répertoire languages/ de MediaWiki - voir la Documentation des messages.

Il est préférable d'utiliser des mots entiers avec les mots magiques PLURAL, GENDER, et GRAMMAR. Par exemple  est meilleur que. Cela rend la recherche plus facile.



Sélecteurs dans les messages…
La valeur actuelle des paramètres influence la syntaxe exacte et les variantes grammaticales des messages. Nous ne nous arrêtons pas à des constructions laides comme « $1 (sub)page(s) of his/her userpage », car elles sont médiocres pour les utilisateurs et nous pouvons faire mieux. A la place, nous implémentons des sélecteurs qui seront exécutés en fonction des valeurs connues au moment de l'exécution. Le texte du message statique fournit alors chacun des choix possibles dans une liste, précédé du nom du sélecteur et d'une référence à la valeur qui fait la différence.

Ceci ressemble à la manière dont les sont appelées dans MediaWiki. Plusieurs types de sélecteurs sont disponibles. Cela ne fonctionne que si vous faites une analyse complète, ou une transformation des  dans les messages.



…avec les nombres via PLURAL
MediaWiki prend en charge les pluriels, ce qui rend le produit plus attractif. Par exemple :

S'il existe une forme plurielle qui dépend d'un nombre particulier, il est facile d'utiliser la syntaxe suivante :



Attention à l'utilisation de PLURAL sur tous les nombres

 * Voir aussi : Plural

Lorsqu'un nombre doit être inséré dans un message textuel, il faut savoir que certaines langues devront utiliser PLURAL même s'il est toujours plus grand que 1. La raison est que PLURAL dans les langues autres que l'anglais peut apporter des formes différentes et complexes comme 1er, 1ère, 1ers, 1ères, … 2nd, 2nde, 3e, … etc.

N'essayez pas de fournir trois messages différents dans les cas où sont comptés Aucun élément, Un élément, Plusieurs éléments. Mais utilisez plutôt un seul message pour l'ensemble et laissez aux traducteurs et à PLURAL le soin de le traiter correctement dans leur langue respective.

Si possible, incluez toujours le nombre en tant que paramètre. Ajoutez toujours la syntaxe  aux messages source quand c'est possible même si cela n'a pas de sens en anglais. La syntaxe guide les traducteurs.

Les nombres fractionnaires sont acceptés mais les règles du pluriel peuvent ne pas être complètes.



Passer le nombre d'éléments de liste comme paramètre des messages qui ont rapport aux listes
Ne supposez pas qu'il n'existe que le singulier et le pluriel. Beaucoup de langues possédent plus de deux formes qui dépendent du nombre actuel utilisé et qui doit être utilisé par les variantes de la grammaire en fonction du nombre d'éléments possibles dans la liste lorsqu'il s'agit d'exprimer ce qui est listé dans la liste affichée aux lecteurs. Ainsi, quand votre code évalue une liste, incluez  dans les paramètres du titre, les introductions, les pieds de page et les autres messages concernés par liste, même si le compteur n'est pas utilisé en anglais. Il existe une manière neutre de parler des listes cachées, vous pouvez donc avoir des liens vers des listes sur des pages supplémentaires sans avoir à compter les éléments auparavent.



…avec des noms d'utilisateur via GENDER
Lorsque vous devez employer un nom d'utilisateur dans un message, passez-le en paramètre du message et ajoutez une information dans le message de documentation comme quoi le genre est pris en charge. S'il est probable que GENDER soit utilisé dans les traductions pour les langues utilisant l'inflexion du genre, ajoutez-le explicitement dans le message source anglais.

Si vous vous adressez directement à l'utilisateur actuellement connecté, laissez à vide le paramètre du nom d'utilisateur :

Si vous incluez le nom de l'utilisateur dans le message (par exemple « »), envisagez d'abord de le passer via  pour vous assurer que les caractères tels que   ou   ne sont pas interprétés.



Les utilisateurs possèdent des genres grammaticaux

 * Voir aussi Gender

Lorsqu'un message parle d'un utilisateur ou concerne celui-ci, ou encore s'adresse à un utilisateur directement, le nom de l'utilisateur doit être passé au message en tant que paramètre. Ainsi les langues qui doivent, ou qui souhaitent utiliser une grammaire plus adaptée en fonction du genre, peuvent le faire. Ceci doit être fait même si le nom de l'utilisateur n'est pas sensé apparaître dans le message comme par exemple dans « informer l'utilisateur/trice sur sa page de discussion  », qui est reformulé en « informer l' sur sa page de discussion  ».

Ceci ne veut pas dire que vous devez systématiquement sexuer les messages du langage : au maximum cherchez à utiliser des fomules neutres qui soient claires et précises.



…selon le contexte des phrases via GRAMMAR
Les transformations grammaticales pour les sont également disponibles. Par exemple en finnois, où il faut absolument que les fichiers soient indépendants du site, par exemple en enlevant les références à Wikipedia. En finnois, « about Wikipedia » devient « Tietoja Wikipediasta » et « you can upload it to Wikipedia » devient « Voit tallentaa tiedoston Wikipediaan ». On ajoute des suffixes en fonction de la manière dont le mot est utilisé, plus des modifications mineures à la base. La liste des exceptions est longue mais parce qu'il n'y a que très peu de mots à traduire, comme le nom du site, nous n'avons pas besoin de les inclure.

MediaWiki possède des fonctions de transformation grammaticales pour plus de 20 langues. Certains d'entre eux ne sont que des dictionnaires de noms de sites pour Wikimedia, mais d'autres possèdent des algorithmes simples mais qui échouent pratiquement sauf dans les cas standards.

Même avant que MediaWiki ne possède les transformations grammaticales arbitraires, il savait déjà faire la différence entre le nominatif et le génitif pour le nom des mois. Cette différence est nécessaire dans certaines langues si vous souhaitez substituer le nom des mois dans les phrases.



Filtrer les caractères spéciaux dans les paramètres et les messages
L'autre problème (plus simple) avec la substitution des paramètres est l'échappement HTML. Bien qu'il paraisse beaucoup plus simple, MediaWiki le traite assez mal.



Utilisation des messages en PHP
Voici un exemple simple :

est une fonction globale qui agit comme une surcouche de la classe Message et qui permet de créer un objet Message. Cet exemple appelle ensuite la méthode  de Message qui recherche le texte du message 'submit' dans la langue actuelle, réalise certaines transformations de langage (comme gender et plural), et renvoie le texte non échappé du message.

Voici un exemple plus complexe où le message utilise un compteur et prend en charge la gestion du pluriel linguistique :

Les sections suivantes expliquent le code.

Paramètres
Etant donné un message comme celui-ci :

Vous pouvez passer les paramètres aux messages qui en ont besoin, de différentes façons :

La première approche est très commune; utilisez le second cas lorsque vous avez des types différents de paramètres et le troisième pour construire dynamiquement des objets Message à partir d'autres données. Il existe des différents types de paramètres :


 * : Substitution normale des paramètres du message.
 * : Substitue le paramètre après que le message ait été traité par ailleurs; cela signifie que ces paramètres ne sont pas disponibles pour les fonctions de l'analyseur syntaxique, et qu'is ne sont pas non plus échappés même quand le mode de sortie échappé est utilisé (voir ci-dessous). Assurez-vous donc de les échapper correctement par vous-même.
 * : Comme, mais réalise l'échappement. Utile quand vous passez des entrées utilisateur pouvant contenir du wikicode à ne pas analyser.

Chaque fonction du second groupe formate la valeur d'une manière particulière avant la substitution. doit être utilisé si le message utilise. Dans certains cas vous ne souhaitez pas l'utiliser alors que vous avez un nombre ; c'est le cas par exemple d'un identifiant de version. Les autres fonctions correspondent aux fonctions du langage,  ,  ,   et  , et ne sont que des raccourcis pour les appeler.

Langue
Pour réécraser la langue dans laquelle vous voulez le message, il existe une méthode et un raccourci pour le cas habituel d'utilisation de la langue du contenu du wiki. Pour le dernier cas, vous pouvez utiliser soit un code de langue ou un objet de langue. La chaîne habituelle concernant le repli des langues s'applique, donc le message que vous voyez peut être dans une langue différente de celle qui a été demandée, lorsque la traduction n'existe pas.



Modes des sorties et échappement
La classe Message, et donc l'objet renvoyé par wfMessage, comprend cinq modes de sortie :


 * - renvoie le texte du message comme il est; seuls les paramètres sont substitués
 * - transforme le texte du message (MessageCache::transform qui transforme tous les ' – ', comme par exemple les plurals), mais sans faire d'échappement ni de nettoyage
 * - même chose que 'text', mais réalise l'échappement pour l'utiulisation en HTML
 * - analyse le texte des messages à partir du wikicode vers le HTML et le nettoie (MessageCache::parse appelle l'analyseur)
 * - la sortie est placée dans un élément HTML de niveau bloc s'il ne l'était pas déjà, similaire à OutputPage::addWikiMsg

Rappelez-vous que les fonctions Html:: échappent tout ce qui leur est transmis, donc utilisez le format text avec celles-ci pour éviter d'échapper deux fois. Par conséquent le format de sortie le plus commun est text. Assurez-vous également d'utiliser parse ou parseAsBlock si le message contient du wikicode à l'intérieur, sinon le wikicode sera simplement échappé et affiché comme un simple texte.

Si vous utilisez  ou, vous devez toujours spécifier un type de sortie. convient si la sortie est faite par.



Mode de sortie à utiliser
D'une manière générale, les modes les plus communs que vous utiliserez seront  et. Utilisez ->parse là où le balisage html est pris en charge, et  là où le contenu sera du html échappé ou lorsque les balises html ne sont pas supportées.

Quelques cas communs :
 * Si la partie textuelle de (troisième argument) vous sert à passer le message, utilisez  . A la place, vous pouvez aussi utiliser  avec le mode.
 * Si vous passez du texte de (troisième argument), utilisez généralement.
 * Si vous passez des attributs (second argument) de ou, utilisez.
 * Si vous construisez manuellemrnt les attributs html, vous devez utiliser . Néanmoins vous n'avez jamais à construire des attributs html.
 * Pour où   est un objet OutputPage, utilisez   ou  . Néanmoins réfléchissez s'il ne vaut pas mieux utiliser  à la place.
 * Pour $out->addHTML utiliser



Chaînage des méthodes
La plupart des méthodes Message renvoient l'objet courant, de sorte que vous pouvez facilement les appeler sur l'objet l'une après l'autre avant de finalement, renvoyer son texte. Ceci est appelé chaînage des méthodes. Voici un exemple :



Méthodes supplémentaires pour imprimer les messages
La fonctions générale pour les messages de MediaWiki est. However, since in a message the value of magic words can depend on the context, there are various wrappers to this function, that automatically set the correct context.

OutputPage possède quelques méthodes qui permettent de concaténer directement à la sortie générée. Les méthodes utiles sont :

Both of the above parse the wikitext in the context of the current page before appending it to output buffer.

Classes extending ContextSource have a method  that automatically sets the current context (language, current page etc.). C'est pourquoi il est recommandé d'utiliser pour ces classes, comme avec les pages spéciales. Voici une liste non exhaustive de telles classes :
 * CategoryViewer
 * HTMLForm
 * LogEventsList
 * DifferenceEngine
 * OutputPage
 * IndexPager
 * ImageHistoryList
 * ApiBase
 * ChangesList
 * Skin

Exemples corrects d'utilisation : Exemples incorrects d'utilisation :



Utiliser les messages en JavaScript

 * See also ResourceLoader/Core modules#mediaWiki.message
 * Note: this page only deals with MediaWiki core. See the specific documentation instead for the jquery.i18n module.



Récupérer les messages pour le client
To use the messages, we need to make sure that the messages are available at client side first. This can be done using either a ResourceLoader module (most common) or an API query from JavaScript (rare).

<span id="Using_a_ResourceLoader_module">

Utiliser un module ResourceLoader

 * See also Manual:$wgResourceModules#Details
 * Note: This is the most common method of delivering messages. You should use this unless you have a good reason not to.

We are going to use ResourceLoader to make sure that the messages are available at the client side. For this, in your ResourceLoader modules, define the messages to be exported to the client side.

If you plan to use the  to generate HTML from wikitext in interface messages, then it is important to load the mediawiki.jqueryMsg module.

Example (extension.json):

<span id="Using_an_API_query_from_JavaScript">

Utiliser une requête API à partir de JavaScript

 * Note: This is not a common way of loading messages. You should only use this if there is a good reason why you can't use the ResourceLoader module method above.

You can use the following code:

To get the messages in some language other than the  language, use getMessages instead of loadMessagesIfMissing, and supply the target language as the "amlang" field of the optional second parameter, like so:

For older MediaWiki versions before 1.27, use the following:

<span id="Use_of_the_messages">

Utilisation des messages
The messages defined in the above example will be available at client side and can be accessed by.

For example: $.( mw.message. ); Note how we use jQuery  method to escape our output properly when using mw.message   format.

If your message contains wikitext formatting, you can instead use the following: $.( mw.message. ); Here we use jQuery  method to insert the DOM nodes returned by mw.message   format.

In older code you might also encounter the following: ( was not available until MediaWiki 1.27) $.( mw.message. ); $.( mw.message. );

There are other correct combinations, but whenever possible, stick to the patterns above to avoid XSS vulnerabilities and make your code easier to understand for others.

We can also pass the dynamic parameters to the message (i.e. the values for $1, $2, etc.) as shown below.

In the above examples, note that the message should be defined in an i18n file. If the message key is not found in any i18n file, the result will be the message key in curved angle brackets U+29FC/U+29FD (part of mathematical symbols), like '⧼message-key-foo⧽'. In older versions of MediaWiki, the message key was returned in ASCII angle brackets, like '&lt;message-key-foo&gt;', and this could generate invalid or fake HTML elements. In the case where the message key does not exists, the  method of the returned message object will also return false instead of true.

To use a message that must not go through the parser (e.g. when passing JSON data as messages, or when the message will be used as preloaded text of a page), use:

<span id="Format_options">

Options de format
If you don't specify the output format, mw.message just returns a Message object. To output the message itself, you should specify an output format. The formats are mostly the same as in PHP side:


 * Returns the message text as-is; only parameters are substituted.
 * Transforms the message text (all supported  blocks are replaced with transformed results).  See  for details of what is supported.  For example, certain keywords (  (but only without parameters), ,   etc.) work, but tranclusion (e.g.  ) and server-side Magic words such as  or      do not work,
 * HTML escaped version of.
 * Parses the message text from wikitext to HTML. This supports everything from  mode, as well as most links, and allowlisted HTML.
 * Like, but returns a jQuery collection instead of a HTML string.

Warning: If the mediawiki.jqueryMsg module is not loaded, all of the above methods behave essentially like  with possible escaping.

Note: There is no equivalent of parseAsBlock. Where necessary, wrap the output in a block element yourself.

Paramètres
Parameters can be specified as additional arguments to. They can be passed as strings or as DOM nodes / jQuery collections.

Unlike in PHP, wikitext in the parameters is not parsed. Effectively, all string parameters behave like.

DOM/jQuery parameters can be used to achieve the equivalent of.

There is no support for other parameter formats. Instead of, you must format numbers before passing them as parameters, using.

<span id="Feature_support_in_JavaScript">

Support des fonctionnalités dans JavaScript
JavaScript messages only support a small subset of wikitext syntax. Supported features include:


 * Internal links (except pipe trick)
 * Explicit external links (no auto-numbered and free links)
 * Magic words SITENAME, PAGENAME, PAGENAMEE, (in MW 1.38+) SERVERNAME
 * Parser functions PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst
 * HTML tags which are allowed in wikitext (HTML must be well-formed)
 * HTML entities,  ,  ,  ,
 * The tag

Notable wikitext syntax that is not supported:


 * Templates
 * Non-local interwiki links
 * All other parser functions and magic words
 * Modules (for example Module:String)
 * All other XML-like tags (extension tags)
 * Bold and italic,   (use ,  instead)
 * Lists using,   (use /,  instead)
 * Definition lists / indents using,   (use , ,  instead)
 * Multiple paragraphs (use instead)
 * Self-closing HTML tags
 * Comments )

The doc-jqueryMsg template can be used to document such messages, to let translators know which wikitext restrictions apply.

Fonction xmw.msg
The  function is commonly used as a shortcut for.

<span id="Exporting_messages_through_ResourceLoader_callbacks">

Exporter les messages via une procédure de callback du ResourceLoader
If you need to process a message on the server and send the result to the client (e.g. because you need to parse the message using parsing features that aren't supported in JS), you can do that with a package files callback in your ResourceLoader module. When you do this, take care to use, because using  will cause errors.

<span id="Using_messages_in_Lua">

Utilisation des messages en Lua
Modules written in Lua using run similarly to templates and have access to MediaWiki messages. The MediaWiki Lua library includes the mw.message class for processing messages. Refer to the full Lua message library documentation for the full API. Here is a simple example:

<span id="Notes_about_gender,_grammar,_plural">

Notes à propos de gender, grammar et plural

 * See also ; the syntax itself is documented at Help:Magic words and related.

In general, GENDER, GRAMMAR and PLURAL magic words work identically in both PHP and JavaScript sides.


 * 1) You must use ,  ,   or   output formats for them to work.
 * 2) * In PHP, you can use wfMessage or.
 * 3) * In JavaScript, make sure your resource loader module depends on  (see #Using messages in JavaScript).
 * 4) You need to pass the relevant parameter as normal parameter to the message.
 * 5) * The parameter is the number for PLURAL; the plain text or wikitext-escaped username for GENDER in PHP; the gender from preferences or a user object for GENDER in JavaScript (see below).
 * 6) * For enabling plural and correct number localization in PHP, you need to use  for the number, see also #Chaining.
 * 7) * For enabling plural and correct number localization in JavaScript, you need to use  for the number

<span id="PLURAL_syntax_example">

Exemple de syntaxe PLURAL
<span id="GENDER_in_JavaScript">

GENDER en JavaScript
If you have a message, say,, in JavaScript, you can use it as given below:

Instead of passing the gender directly, we can pass any "User-like" object with a gender option. For example, the current user object.

If the gender passed is invalid or unknown, the gender neutral form will be used as defined for each language. Pass  if you intentionally want the neutral form.

Finally, if you want to use the gender of the current user, you can pass an empty string:

<span id="PLURAL_in_JavaScript">

PLURAL en JavaScript
If you have a message, say , in JavaScript, you can use it as given below:

<span id="Help_with_replacing_deprecated_wfMsg*_functions">

Aide au remplacement des fonctions obsolètes wfMsg*
The code using these functions often has incorrect escaping and other code quality issues, so it's also recommended to
 * replace all Xml:: functions with their Html:: equivalents, which make it easier to do the right thing;
 * where possible, avoid globals and use  (see above);
 * replace  with   where appropriate.

<span id="See_also">

Voir aussi

 * API:Allmessages
 * m:Help:HTML in wikitext
 * Message class documentation