API Messages

Les messages MediaWiki 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 $1, $2, $3, … 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 {{PLURAL:$1|subpage|subpages}} est meilleur que sub{{PLURAL:$1|page|pages}}. Cela rend la recherche plus facile.

Faire référence à d'autres messages

Il est quelques fois pratique dans un message, de faire référence aux sous-messages, par exemple dans les phrases comme « Utiliser le bouton X » ou « Voir la page Y », afin de s'assurer que les traductions sont cohérentes. Pour faire cela, vous pouvez utiliser la syntaxe suivante :

• {{int:X}} - pour utiliser le sous-message dans la langue de l'interface. Ceci est souvent utilisé lorsque l'on fait référence aux boutons de formulaire ou à la navigation du site, comme showpreview.
• {{MediaWiki:Y}} - pour utiliser le sous-message dans la langue du contenu. Ceci est utilisé lorsque le sous-message définit un nom traductible d'une page localisée, comme mainpage, grouppage-sysop, policy-url.
• {{#Special:Z}} - pour utiliser le nom d'une page spéciale dans la langue du contenu.

Si vous souhaitez quelque chose de plus compliqué (comme le sous-message utilisé dépendant de la configuration), analyser-le dans votre code et passez le sous-message complet en paramètre.

Exemple :

Before saving, use the {{int:foo-test}} button to test the changes. Visit [[{{MediaWiki:foo-help}}|the help page]] to learn more.Customize this feature at [[{{#Special:Preferences}}]].

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 Fonctions d'analyse 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 :

'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}',

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

'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'

Attention à l'utilisation de PLURAL sur tous les nombres

Voir aussi : translatewiki: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 1^er, 1^ère, 1^ers, 1^ères, … 2^nd, 2^nde, 3^e, … 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 {{PLURAL:}} 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 count( $list ) 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

'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.'

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 :

'foobar-logged-in-user' => 'You said {{GENDER:|you were male|you were female|nothing about your gender}}.'

Version de MediaWiki :

≥ 1.31 Gerrit change 398772

Si vous incluez le nom de l'utilisateur dans le message (par exemple « $1 vous a remercié(e).»), envisagez d'abord de le passer via wfEscapeWikitext() 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 : translatewiki: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'{{GENDER:$1|utilisateur|utilisatrice|utilisateur}} 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 langues agglutinantes (Q171263) 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. Certaines d'entre elles 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

Avertissement :

Vérifiez que vous utilisez toujours un des modes de sortie mentionnés ci-dessous

Voici un exemple simple :

$out = Xml::submitButton( wfMessage( 'submit' )->text() );

wfMessage() 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 text() 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 :

$out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() );

Les sections suivantes expliquent le code.

Paramètres

Etant donné un message comme celui-ci :

{
    "msg": "Values are $1, $2"
}

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

wfMessage( 'msg', 'param1', 'param2' )->plain();
wfMessage( 'msg' )->params( 'param1', 'param2' )->plain();
wfMessage( 'msg', [ 'param1', 'param2' ] )->plain();

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 :

wfMessage( 'msg' )->params( $username )->plain();
wfMessage( 'msg' )->rawParams( $link )->plain();
wfMessage( 'msg' )->plaintextParams( $userInput )->plain();

wfMessage( 'msg' )->numParams( $count )->plain();
wfMessage( 'msg' )->durationParams( $duration )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->expiryParams( $expiry )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->timeperiodParams( $period )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->sizeParams( $size )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->bitrateParams( $bitrate )->plain(); // MediaWiki 1.22+

params()

Substitution normale des paramètres du message.

rawParams()

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.

plaintextParams()

Comme rawParams(), 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. numParams() doit être utilisé si le message utilise {{PLURAL:}}. 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 formatDuration, formatExpiry, formatTimePeriod, formatSize et formatBitrate, 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.

wfMessage( 'message-key' )->inContentLanguage();
wfMessage( 'message-key' )->inLanguage( $lang );

Modes des sorties et échappement

La classe Message, et donc l'objet renvoyé par wfMessage(), comprend cinq modes de sortie :

• plain() - renvoie le texte du message comme il est; seuls les paramètres sont substitués
• text() - transforme le texte du message (voir MessageCache::transform()) en changeant tous les {{}} y compris les modèles et les fonctions d'analyse syntaxique comme PLURAL et GENDER, mais sans faire d'échappement ni de nettoyage
• escaped() - même chose que 'text', mais réalise l'échappement pour l'utiulisation en HTML
• parse() - analyse le texte des messages à partir du wikicode vers le HTML et le nettoie (MessageCache::parse() appelle l'analyseur)
• parseAsBlock() - 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 wfMessage() ou $this->msg(), vous devez toujours spécifier un type de sortie. text() convient si la sortie est faite par addWikiText().

Mode de sortie à utiliser

D'une manière générale, les modes les plus communs que vous utiliserez seront ->parse() et ->text(). Utilisez ->parse() là où le balisage html est pris en charge, et ->text() 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 Html::element (troisième argument) vous sert à passer le message, utilisez ->text(). A la place, vous pouvez aussi utiliser Html::rawElement() avec le mode ->parse().
• Si vous passez du texte de Html::rawElement() (troisième argument), utilisez généralement ->parse().
• Si vous passez des attributs (second argument) de Html::rawElement() ou Html::element(), utilisez ->parse().
• Si vous construisez manuellemrnt les attributs html, vous devez utiliser ->escaped(). Néanmoins vous n'avez jamais à construire des attributs html.
• Pour $out->addWikiText() où $out est un objet OutputPage, utilisez ->text() ou ->plain(). Néanmoins réfléchissez s'il ne vaut pas mieux utiliser $out->addWikiMsg à la place.
• Pour $out->addHTML() utiliser ->parse()

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 :

wfMessage( 'key' )
	->params( 'apple' )
	->numParams( $numOfApples )
	->setContext( $context )
	->inContentLanguage()
	->parse()

Méthodes supplémentaires pour imprimer les messages

La fonctions générale pour les messages de MediaWiki est wfMessage. Cependant, étant donné que dans un message, la valeur des mots magiques peut dépendre du contexte, il existe différentes variantes de surcouche de cette fonction, qui définissent automatiquement le contexte correct.

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

$out->addWikiMsg( 'pageheader' );
$out->wrapWikiMsg( '<div class="error">\n$1\n</div>', [ 'someerrormessage', $user->getName() ] );

Les deux fonctions ci-dessus analysent ensemble le wikicode dans le contexte de la page courante avant de le rajouter dans le tampon de sortie.

Les classes qui étendent ContextSource ont une méthode msg qui définit automatiquement le contexte courant (langue, page courante etc.). C'est pourquoi il est recommandé d'utiliser $this->msg() 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

Avertissement :

La classe QuickTemplate et ses sous-classes (BaseTemplate) possèdent une méthode appelée msg différente de celle de ContextSource. Dans ces classes $this->msg() va produire simplement le texte échappé du message.

Exemples corrects d'utilisation :

wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();

Exemples incorrects d'utilisation :

wfMessage( 'key', 345 )->parseInline(); # Le nombre n'est pas formaté correctement
$this->msg( 'key', 345 )->numParams( 234 )->plain() # La syntaxe de Plural n'est pas convertie en format à plat

Utiliser les messages en JavaScript

Voir aussi : ResourceLoader/Core modules#mediaWiki.message

Cette page ne traite que du noyau MediaWiki. Pour le module jquery.i18n, voir la documentation spécifique.

Récupérer les messages pour le client

Pour utiliser les messages, nous devons nous assurer d'abord que les messages sont disponibles du côté client. Ceci peut être fait en utilisant soit un module ResourceLoader (cas le plus fréquent) ou une requête API à partir de JavaScript (plus rare).

Utiliser un module ResourceLoader

Voir aussi : Manual:$wgResourceModules

C'est la manière la plus commune pour délivrer des messages. Vous devez l'utiliser sauf si vous avez une bonne raison de ne pas le faire.

Nous allons utiliser ResourceLoader pour vérifier que les messages sont disponibles côté client. Pour cela vous devez définir dans vos modules ResourceLoader, les messages à exporter côté client.

Si vous souhaitez utiliser mw.message(…).parse() pour générer le HTML à partir du wikicode dans les messsages d'interface, alors il est important de charger le module mediawiki.jqueryMsg.

Exemple (extension.json) :

{
	"ResourceModules": {
		"ext.abuseFilter.edit": {
			"scripts": "ext.abuseFilter.edit.js",
			"messages": [
				"abusefilter-edit-syntaxok",
				"abusefilter-edit-syntaxerr",
				"abusefilter-http-error",
				"abusefilter-edit-throttle-placeholder",
				"abusefilter-edit-tag-placeholder",
				"abusefilter-edit-warn-leave",
				"unknown-error",
				"jan",
				"feb",
				"mar"
			],
			"dependencies": [
				"mediawiki.util",
				"mediawiki.api",
				"mediawiki.confirmCloseWindow",
				"jquery.textSelection",
				"jquery.spinner",
				"oojs-ui-core",
				"oojs-ui-widgets"
			]
		}
	}
}

Utiliser une requête API à partir de JavaScript

Ce n'est pas une manière habituelle pour charger des messages. A utilisez uniquement si vous avez une bonne raison de ne pas pouvoir utiliser la méthode du module ResourceLoader ci-dessus.

Vous pouvez utiliser le code suivant :

Version de MediaWiki :

≥ 1.27

// Quand : le module 'mediawiki.api' est chargé, et que la page est prête
$.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Alors : chargez les messages dont vous avez besoin (s'ils ne sont pas encore chargés)
    .then( function() {
        return new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] );
    } )
    // Alors : utilisez-les dans votre code
    .then( doStuff );

Pour avoir les messages dans une langue donnée différente de UserLanguage, utilisez getMessages au lieu de loadMessagesIfMissing, et indiquez la langue cible dans le champ amlang du second paramètre optionnel ainsi :

// Quand : le module 'mediawiki.api' est chargé, il n'est pas nécessaire d'attendre que la page soit prête
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Alors : récupérer quelques messages en French (code de langue 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Alors : utilisez-les dans votre code
    .then( doStuff );
// doStuff est une fonction qui reçoit pour premier paramètre, un objet similaire à :
// { february: "février", january: "janvier", march: "mars" }

Pour des versions plus anciennnes de MediaWiki (avant la 1.27), utilisez ceci :

/** @renvoyer l'instance de jQuery.Promise */
function loadMessages( messages ) {
	return new mw.Api().get( {
		action: 'query',
		meta: 'allmessages',
		ammessages: messages.join( '|' ),
		amlang: mw.config.get( 'wgUserLanguage' )
	} ).then( function ( data ) {
		$.each( data.query.allmessages, function ( i, message ) {
			if ( message.missing !== '' ) {
				mw.messages.set( message.name, message['*'] );
			}
		} );
	} );
}

loadMessages( [ 'january', 'february', 'march' ] ).then( doStuff );

Utilisation des messages

Les messages définis dans l'exemple ci-dessus seront disponibles côté client et peuvent être récupérés par mw.message( 'message-key-name' ).

Par exemple :

$( '<div>' ).text( mw.message( 'translate-msggroupselector-projects' ).text() );

Notez la manière d'utiliser la méthode jQuery text pour échapper proprement notre sortie lorsque nous utilisons le format mw.message text.

Si votre message contient du wikicode formaté, vous pouvez à la place utiliser ceci :

$( '<div>' ).append( mw.message( 'translate-msggroupselector-projects' ).parseDom() );

Ici nous utilisons la méthode jQuery append pour insérer les noeuds DOM renvoyés par le format mw.message parseDom.

Dans du code ancien, vous pouvez aussi rencontrer ceci : (parseDom n'était pas disponible avant MediaWiki 1.27)

$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).escaped() );
$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).parse() );

Il existe d'autres combinaisons toutes aussi valides, mais autant que possible, appliquez les modèles ci-dessus pour éviter les failles XSS et rendre votre code compréhensible pour les autres.

Nous pouvons aussi passer au message, les paramètres dynamiques (c'est à dire les valeurs de $1, $2, etc.) comme indiqué ci-dessous.

$( '<div>' ).text( mw.message( 'hello-user', username ).text() );

Dans les exemples ci-dessus, notez que le message doit être défini dans un fichier i18n. Si la clé du message n'est trouvée dans aucun fichier i18n, le résultat sera la clé du message entourée d'accolades arrondies U+29FC/U+29FD (appartenant aux symboles mathématiques), comme '⧼message-key-foo⧽'. Dans des versions plus anciennes de MediaWiki, la clé du message était renvoyée en ASCII entre crochets, comme '<message-key-foo>', ce qui pouvait générer des éléments HTML invalides ou erronnés. Dans le cas où la clé du message n'existe pas, la méthode .exists() de l'objet message renvoyé rendra également false à la place de true.

Pour utiliser un message qui ne doit pas passer par l'analyseur (par exemple quand vous transférez des données JSON en tant que message, ou lorsque le message sera utilisé comme texte préchargé d'une page), utilisez :

mw.message( 'foobar' ).plain()

Options de format

Si vous ne précisez pas le format de sortie, mw.message ne renvoie qu'un objet Message. Pour obtenir le message lui-même, vous devez indiquer un format de sortie. Les formats sont pratiquement les mêmes que ceux du côté PHP :

• mw.message( 'foobar' ).plain() renvoie le texte du message tel qu'il est; seuls les paramètres sont substitués
• mw.message( 'foobar' ).text() Transforme le texte des messages (tous les blocs {{}} pris en charge sont remplacés par les résultats transformés). Voir la section des fonctionnalités supportées en JavaScript pour le détail. Par exemple certains mots-clés, ({{int:}} (mais uniquement sans paramètres), {{GENDER}}, {{SITENAME}} etc.) fonctionnent mais la tranclusion (par exemple {{MediaWiki:}}) et les mots magiques côté serveur tels que {{NUMBEROFEDITS}} ou {{ns:Project}} ne fonctionnent pas,
• mw.message( 'foobar' ).escaped() Version HTML échappée de text.
• mw.message( 'foobar' ).parse() Analyse le texte du message à partir du wikicode pour en faire du HTML. Ceci prend tout en charge en mode text, comme la plupart des liens, et permet les listes de HTML.
• mw.message( 'foobar' ).parseDom() Comme parse(), mais renvoie une collection jQuery au lieu d'une chaîne HTML.

Avertissement :

Si le module mediawiki.jqueryMsg n'est pas chargé toutes les méthodes ci-dessus se comportent essentiellement comme plain() avec éventuellement un échappement.

Il n'y a pas d'équivalent de parseAsBlock. Partout où c'est nécessaire, incluez personnellement la sortie dans un élément de bloc.

Paramètres

Les paramètres peuvent être spécifiés en tant qu'arguments supplémentaires de mw.message(). Ils peuvent être passés comme des chaînes ou comme des noeuds DOM ou des collections jQuery.

A la différence du PHP, le wikicode dans les paramètres n'est pas soumis à l'analyse syntaxique. Effectivement tous les paramètres de type chaîne se comportent comme plaintextParams().

Les paramètres DOM ou jQuery peuvent être utilisés pour compléter l'équivalent de rawParams().

Les autres formats de paramètre ne sont pas pris en charge. Au lieu de numParams(), vous devez formater les nombres avant de les passer en paramètre, en utilisant mw.language.convertNumber().

$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() );

Support des fonctionnalités en JavaScript

Avertissement :

Le support du wikicode dans les messages JavaScript nécessite que le module mediawiki.jqueryMsg soit chargé, sinon ces fonctionnalités seront simplement ignorées.

Les messages JavaScript ne supportent qu'un petit sous-ensemble de la syntaxe wikicode. Les fonctionnalités prises en charge comprennent :

• Liens internes (sauf l'utilisation des structures avec le caractère pipe '|')
• Les liens externes explicites (sans numérotation automatique ni les liens libres)
• Les mots magiques SITENAME, PAGENAME, PAGENAMEE, (dans MW 1.38+) SERVERNAME
• Les fonctions d'analyseur PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst
• Les balises HTML autorisées en wikicode (le code HTML doit être bien formé)
• Les entités HTML ', ", <, >, &
• La balise ‎<nowiki>

Syntaxe wikicode remarquable qui n'est pas prise en charge :

• Les modèles (templates)
• Les liens interwikis non locaux
• Toutes les autres fonctions d'analyse ainsi que les autres mots magiques
• Les modules (par exemple Module:String)
• Toutes les autres balises de type XML (balises des extensions)
• L'écriture en gras et en italique ''', '' (utilisez ‎<b>, ‎<i> à la place)
• Les listes qui utilisent *, # (à remplacer par ‎<ul> ou ‎<ol> et ‎<li>)
• Les définitions de listes ou d'indentations utilisant ;, : (à remplacer par ‎<dl>, ‎<dt>, ‎<dd>)
• Les paragraphes multiples (utiliser ‎<p> à la place)
• Les balises HTML auto-fermantes
• Les commentaires <!-- -->
• Certains types d'imbrications (par exemple {{PLURAL:$1|<strong>$1</strong>}})

Le modèle doc-jqueryMsg peut être utilisé pour documenter de tels messages, et permettre ainsi aux traducteurs de connaître les restrictions qui s'appliquent au wikicode.

mw.msg

La fonction mw.msg() est habituellement utilisée comme raccourci pour mw.message().text().

Exporter les messages via une procédure de callback du ResourceLoader

Si vous voulez traiter un message sur le serveur et renvoyer le résultat au client (par exemple parce que vous avez besoin d'analyser le message à l'aide des fonctions d'analyse qui ne sont pas prises en charge en JaaScript), vous pouvez le faire avec une procédure de callback des fichiers du paquet dans votre module ResourceLoader. Quand vous faites ceci, veillez à utiliser $context->msg() car wfMessage() provoque des erreurs.

Utilisation des messages en Lua

Les modules écrits en Lua et utilisant Scribunto s'exécutent de manière similaire aux modèles et ont accès aux messages MediaWiki. La bibliothèque MediaWiki Lua inclut la classe mw.message pour le traitement des messages. Voir la documentation complète de la bibliothèque des messages Lua pour l'API entière. Voici un exemple simple :

local p = {}

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- Ceci assure l'adaptation locale des nombres
	-- Afficher le message dans la langue du wiki. frame:preprocess étend la clause {{plural}}.
	return frame:preprocess( nmembersMsg:plain() )
end

return p

Notes à propos de GENDER GRAMMAR et PLURAL

Voir aussi la section des Sélécteurs dans les messages…; la syntaxe est elle-même documentée dans l'internationalisation des mots magiques et associés.

En général les mots magiques GENDER, GRAMMAR et PLURAL fonctionnent de la même manière du côté PHP que du côté JavaScript.

1. Vous devez utiliser un format de sortie parmi text, escaped, parse ou parseAsBlock pour qu'ils fonctionnent.
   • En PHP, vous pouvez utiliser wfMessage ou $this->msg.
   • En JavaScript, assurez-vous que votre module chargeur de ressources dépend bien de jqueryMsg (voir la section des messages en JavaScript).
2. Vous devez passer au message le paramètre ad'hoc en tant que paramètre normal.
   • Le paramètre est le numéro pour PLURAL; le texte brut ou le nom d'utilisateur en wikicode échappé pour GENDER en PHP; le genre tel que fourni dans les Preferences ou un objet pour GENDER en JavaScript (voir ci-dessous).
   • Pour permettre le pluriel et la traduction correcte des nombres en PHP, vous devez utiliser numParams pour les nombres, voir aussi le chaînage.
   • Pour activer la traduction du pluriel et du nombre correct en JavaScript, vous devez utiliser mw.language.convertNumber pour le nombre

Exemple de syntaxe PLURAL

# Pluriel simple
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'

GENDER en JavaScript

Ceci nécessite un jqueryMsg explicite, voir la section des messages en JavaScript.

Si vous avez un message, disons "message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article" en JavaScript, vous pouvez l'utiliser ainsi :

mw.message( 'message-key-gender-foo', 'male' ).text(); // renvoie 'he created an article'
mw.message( 'message-key-gender-foo', 'female' ).text(); // renvoie 'she created an article'
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // renvoie 'they created an article'

Au lieu de passer le genre directement nous pouvons passer n'importe quel objets du type utilisateur avec une option de genre. Par exemple, l'objet utilisateur courant mw.user.

var user = mw.user; // utilisateur actuel
mw.message( 'message-key-gender-foo', user ).text(); // Le message renvoyé le sera en fonction du genre de l'utilisateur actuel.

Si le genre qui est passé est non valide ou inconnu, c'est la forme du gendre neutre qui sera utilisée telle que définie pour chaque langue. Passez 'unknown' si vous devez volontairement utiliser la forme neutre.

Enfin si vous voulez utiliser le genre de l'utilisateur actuel, vous pouvez passer une chaîne vide :

// la ligne suivante illustre le contenu du message, vous pouvez exécuter ce code dans la console developpeur
mw.messages.set( 'message-key-gender-foo', '{{GENDER:$1|male|female|unknown}}' );
mw.user.options.values.gender = 'female'; // utilise temporairement vos préférences de genre
mw.message( 'message-key-gender-foo', '' ).text(); // la valeur renvoyée dépend de vos préférences de genre

PLURAL en JavaScript

Ceci nécessite explicitement jqueryMsg, voir la section des messages en JavaScript.

Si vous avez un message, disons 'message-key-plural-foo' => 'There {{PLURAL:$1|is|are}} $1 {{PLURAL:$1|item|items}}' en JavaScript, vous pouvez l'utiliser ainsi :

mw.message( 'message-key-plural-foo', count ).text();
// renvoie 'There is 1 item' si count = 1
// renvoie 'There are 6 items' si count = 6

Aide au remplacement des fonctions obsolètes wfMsg*

Ces fonctions ont été supprimées à partir de MediaWiki 1.27 LTS.

Le code qui utilise ces fonctions possède souvent un échappement incorrect ainsi que d'autres problèmes relatifs à sa qualité, il est recommandé par conséquent de

• remplacer toutes les fonctions Xml:: par leurs équivalents Html::, ce qui permettra de faire plus facilement les choses correctement;
• partout où c'est possible, vous éviterez l'utilisation de variables globales et utiliserez msg() (voir ci-dessus);
• remplacer htmlspecialchars() par ->escaped() si nécessaire.

Modification du code	Description
Au lieu de : wfMsg( 'key' ); écrivez : wfMessage( 'key' )->text();
Au lieu de : wfMsgExt( 'key', SOME_FORMAT, 'apple' ); écrivez : wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();	Le second paramètre indique le mode de sortie, habituellement sous la forme d'un tableau comme array( 'escape' ) mais quelques fois simplement comme 'escape' : il doit être remplacé suivant le contenu de la section Modes de sortie et échappement, comme ->escaped().
Au lieu de : wfMsgExt( 'key', array( 'parse' ), 'apple' ); écrivez : wfMessage( 'key', 'apple' )->parseAsBlock();	Utiliser l'analyse complète et inclure la sortie entre des balises HTML de bloc.
Au lieu de : wfMsgExt( 'key', array( 'parseinline' ), 'apple' ); écrivez : wfMessage( 'key', 'apple' )->parse();	Utilise l'analyse syntaxique complète. Parseinline est utilisé car il est plus utile lors de la pré-construction du HTML. Dans le cas habituel il vaut mieux utiliser OutputPage::(add|wrap)WikiMsg.
Au lieu de : wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' ); écrivez : wfMessage( 'key', 'apple', 'pear' )->text();	Endroits où le HTML ne peut pas être utilisé. La transformation des '{{' est réalisée.
Au lieu de : wfMsgHtml( 'key', 'apple' ); écrivez : wfMessage( 'key' )->rawParams( 'apple' )->escaped();	wfMsgHtml n'échappe pas les paramètres : pour obtenir le même résultat vous devez utiliser rawParams; vérifiez que le paramètre et suffisamment sécurisé pour la sortie HTML. Si le message est ensuite produit en HTML, vous devez utiliser escaped() pour la sécurité : cela va échapper également les paramètres et n'est pas toujours souhaité, bien que cela soit sans imortance par exemple lorsque le paramètre est un nombre.
Au lieu de : wfMsgForContent( 'key' ); écrivez : wfMessage( 'key' )->inContentLanguage()->text();	Obtenir un message dans la langue de contenu du wiki. ($wgLanguageCode ).
Au lieu de : wfMsgForContentNoTrans( 'key' ); écrivez : wfMessage( 'key' )->inContentLanguage()->plain();	Fournit un message dans la langue du contenu du wiki ($wgLanguageCode ) mais ne transforme pas le message.
Au lieu de : wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) ); écrivez : wfMessage( 'key' )->inContentLanguage()->isBlank();	Vérifie si le message associé à la clé dans la langue du contenu du wiki est vide. Souvent isDisabled() est un contrôle plus approprié et doit être utilisé à la place.
Au lieu de : wfMsgReal( $error['message'], $error['params'] ); écrivez : ?	Il n'y a pas de simple remplacement, dépend des paramètres. Ne doit jamais être utilisé en première position.
Au lieu de : wfMsgGetKey écrivez : ?	Il n'y a pas de simple remplacement, dépend des paramètres. Ne doit jamais être utilisé en première position.

Voir aussi

• API:Allmessages/fr
• Aide:HTML dans le wikicode
• documentation des classes de messages