View source for Manual:Messages API/ar

<languages/>
{{i18n navigation}}
<span lang="en" dir="ltr" class="mw-content-ltr">{{ll|Help:System message|MediaWiki messages}} can be used in the code through the Message class and its associated methods.</span>

{{ambox
|text = <span lang="en" dir="ltr" class="mw-content-ltr">While the examples throughout this document make use of the global function <code>wfMessage()</code>, in most cases it is best not to use this global function.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Instead, you should use an object that provides a {{ll|Manual:RequestContext.php|RequestContext}}, and call {{phpi|$context->msg()}} on it.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In many classes, you can use {{phpi|$this->msg()}}.</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
==Message parameters==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Some messages take parameters.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">They are represented by <code>$1</code>, <code>$2</code>, <code>$3</code>, … in the (static) message texts, and replaced at run time.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Typical parameter values are numbers (the "3" in "Delete 3 versions?"), or user names (the "Bob" in "Page last edited by Bob"), page names, links and so on, or sometimes other messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">They can be of arbitrary complexity.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The list of parameters defined for each specific message is placed in special file "qqq.json" located in "languages/" folder of MediaWiki - read more in [[Special:MyLanguage/Help:System message#Message documentation|Message documentation]].
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">It's preferable to use whole words with the PLURAL, GENDER, and GRAMMAR magic words.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, <code><nowiki>{{PLURAL:$1|subpage|subpages}}</nowiki></code> is better than <code><nowiki>sub{{PLURAL:$1|page|pages}}</nowiki></code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It makes searching easier.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Referring to other messages ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">It's sometimes convenient to refer to sub-messages in a message, e.g. in phrases like "Use the X button" or "Visit the Y page", to ensure that the translations are consistent.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To do so, you may use the following syntax:</span>

* <code><nowiki>{{int:X}}</nowiki></code> - <span lang="en" dir="ltr" class="mw-content-ltr">to use the sub-message in interface language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is often used when referring to form buttons or site navigation, e.g. [[MediaWiki:Showpreview|showpreview]].</span>
* <code><nowiki>{{MediaWiki:Y}}</nowiki></code> - <span lang="en" dir="ltr" class="mw-content-ltr">to use the sub-message in content language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is used when the sub-message defines a translatable name of a local page, e.g. [[MediaWiki:Mainpage|mainpage]], [[MediaWiki:Grouppage-sysop|grouppage-sysop]], [[MediaWiki:Policy-url|policy-url]].</span>
* <code><nowiki>{{#Special:Z}}</nowiki></code> - <span lang="en" dir="ltr" class="mw-content-ltr">to use the name of a special page in content language.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you need anything more complicated (e.g. the sub-message used depends on configuration), parse it in your code and pass the whole sub-message as a parameter.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Example:
</div>

<syntaxhighlight lang="wikitext">
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}}]].
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
===Switches in messages…===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Parameters values at times influence the exact wording, or grammatical variations in messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We don't resort to ugly constructs like "$1 (sub)page(s) of his/her userpage", because these are poor for users and we can do better.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Instead, we make switches that are parsed according to values that will be known at run time.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The static message text then supplies each of the possible choices in a list, preceded by the name of the switch, and a reference to the value that makes a difference.</span>
<!--SIC! the link is meant to go to the disambiguation page. The biggest possible overview is desired. -->
<span lang="en" dir="ltr" class="mw-content-ltr">This resembles the way {{ll|parser functions}} are called in MediaWiki.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Several types of switches are available.</span>
'''<span lang="en" dir="ltr" class="mw-content-ltr">These only work if you do full parsing, or <code><nowiki>{{</nowiki></code>-transformation, for the messages.</span>'''

<div lang="en" dir="ltr" class="mw-content-ltr">
====…on numbers via PLURAL====
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki supports plurals, which makes for a nicer-looking product.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example:</span>

<syntaxhighlight lang="php">
'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}',
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
If there is an explicit plural form to be given for a specific number, it is possible with the following syntax:
</div>

<syntaxhighlight lang="php">
'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=====Be aware of PLURAL use on ''all'' numbers=====
</div>
{{See also|translatewiki:Plural}}

<span lang="en" dir="ltr" class="mw-content-ltr">When a number has to be inserted into a message text, be aware that some languages will have to use PLURAL on it even if always larger than 1.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The reason is that PLURAL in languages other than English can make very different and complex distinctions, comparable to English 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>, 4<sup>th</sup>, … 11<sup>th</sup>, 12<sup>th</sup>, 13<sup>th</sup>, … 21<sup>st</sup>, 22<sup>nd</sup>, 23<sup>rd</sup>, … ''etc.''</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Do not try to supply three different messages for cases like "no items counted", "one item counted", "more items counted".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Rather, let one message take them all, and leave it to translators and PLURAL to properly treat any possible differences of presentation for them in their respective languages.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Always include the number as a parameter if possible.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Always add <code><nowiki>{{PLURAL:}}</nowiki></code> syntax to the source messages if possible, even if it makes no sense in English.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The syntax guides translators.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Fractional numbers are supported, but the plural rules may not be complete.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=====Pass the number of list items as parameters to messages talking about lists=====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Don't assume that there's only singular and plural.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Many languages have more than two forms, which depend on the actual number used and they have to use [[#…on use context inside sentences via GRAMMAR|grammar]] varying with the number of list items when expressing what is listed in a list visible to readers.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus, whenever your code computes a list, include <code>count( $list )</code> as parameter to headlines, lead-ins, footers and other messages about the list, even if the count is not used in English.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There is a neutral way to talk about invisible lists, so you can have links to lists on extra pages without having to count items in advance.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====…on user names via GENDER====
</div>

<!-- TODO: Integrate this content with the below #Notes about gender, grammar, plural -->

<syntaxhighlight lang="php">
'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.'
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">If you refer to a user in a message, pass the user name as parameter to the message and add a mention in the message documentation that gender is supported.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If it is likely that GENDER will be used in translations for languages with gender inflections, add it explicitly in the English language source message.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you directly address the currently logged-in user, leave the user name as parameter empty:
</div>

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

{{MW version|version=1.31|comment=and after|gerrit change=398772}}
<div lang="en" dir="ltr" class="mw-content-ltr">
If you include the user name into the message (e.g. "{{int|Notification-compact-header-flow-thank}}"), consider passing it through <code>wfEscapeWikitext()</code> first, to ensure that characters like <code>*</code> or <code>;</code> are not interpreted.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=====Users have grammatical genders=====
</div>
{{See also|translatewiki:Gender}}

<span lang="en" dir="ltr" class="mw-content-ltr">When a message talks about a user, or relates to a user, or addresses a user directly, the user name should be passed to the message as a parameter.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">Thus languages having to, or wanting to, use proper gender dependent grammar, can do so.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">This should be done even when the user name is not intended to appear in the message, such as in "inform the user on his/her talk page", which is better made "inform the user on <nowiki>{{GENDER:$1|his|her|their}}</nowiki> talk page" in English as well.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
This does not mean that you are encouraged to "sexualise" messages' language: please use gender-neutral language whenever this can be done with clarity and precision.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
====…on use context inside sentences via GRAMMAR====
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Grammatical transformations for {{Q|171263|agglutinative language}} is also available.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example for Finnish, where it was an absolute necessity to make language files site-independent, ''i.e.'' to remove the Wikipedia references.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In Finnish, "about Wikipedia" becomes "Tietoja Wikipediasta" and "you can upload it to Wikipedia" becomes "Voit tallentaa tiedoston Wikipediaan".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Suffixes are added depending on how the word is used, plus minor modifications to the base.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There is a long list of exceptions, but since only a few words needed to be translated, such as the site name, we didn't need to include it.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki has grammatical transformation functions for over 20 languages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Some of these are just dictionaries for Wikimedia site names, but others have simple algorithms which will fail for all but the most common cases.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Even before MediaWiki had arbitrary grammatical transformation, it had a nominative/genitive distinction for month names.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This distinction is necessary for some languages if you wish to substitute month names into sentences.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
===Filtering special characters in parameters and messages===
</div> 

<div lang="en" dir="ltr" class="mw-content-ltr">
The other (much simpler) issue with parameter substitution is HTML escaping. Despite being much simpler, MediaWiki does a pretty poor job of it.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Using messages in PHP ==
</div>
{{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">Make sure you always use one of the [[#Output modes and escaping|output modes]] mentioned below</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Here is a simple example:
</div>

<syntaxhighlight lang=php>
$out = Xml::submitButton( wfMessage( 'submit' )->text() );
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr"><code>wfMessage()</code> is a global function which acts as a wrapper for the Message class, creating a Message object.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This example then invokes Message method <code>text()</code> which fetches the text of the 'submit' message in the current language, performs certain language transformations (such as gender and plural), and returns the unescaped message text.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Here is a more complex example using a message that takes a count and supports linguistic plural handling:
</div>

<syntaxhighlight lang=php>
$out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() );
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
The following sections explain the code.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
===Parameters===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Given a message like the following:
</div>

<syntaxhighlight lang=json>
{
    "msg": "Values are $1, $2"
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
You pass parameters to messages that need them in several ways:
</div>

<syntaxhighlight lang=php>
wfMessage( 'msg', 'param1', 'param2' )->plain();
wfMessage( 'msg' )->params( 'param1', 'param2' )->plain();
wfMessage( 'msg', [ 'param1', 'param2' ] )->plain();
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
The first approach is most common, use the second approach when mixing different types of parameters, and you can use the third to construct message objects dynamically from other data. There are ''different types of parameters'':
</div>

<syntaxhighlight lang="php">
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+
</syntaxhighlight>

; <code>params()</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">Normal message substitution parameter.</span>
; <code>rawParams()</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">Substitutes the parameter after the message has been otherwise processed; this means that these parameters are not available to parser functions, nor are they escaped if escaping output format is used (see below).</span> <span lang="en" dir="ltr" class="mw-content-ltr">Make sure you escape them properly yourself.</span>
; <code>plaintextParams()</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">Like <code>rawParams()</code>, but does escaping.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It is useful when you pass user input that may contain wikitext that should not be parsed.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Each function from the second group formats the value in a specific way before the substitution.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr"><code>numParams()</code> must be used if the message uses <code><nowiki>{{PLURAL:}}</nowiki></code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In some cases you might not want to use it even though you have a number, for example a revision ID.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The other functions correspond to Language functions <code>formatDuration</code>, <code>formatExpiry</code>, <code>formatTimePeriod</code>, <code>formatSize</code> and <code>formatBitrate</code>, and are just shorthands for calling them directly.</span>


<div lang="en" dir="ltr" class="mw-content-ltr">
===Language===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">To override the language in which you want the message, there is one method and one shortcut for the common case of using wiki content language.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In the latter case you can use either a language code or a language object.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The usual language fallback chains apply, so the actual message you get may be in a different language than requested, if a translation does not exist.</span>

<syntaxhighlight lang=php>
wfMessage( 'message-key' )->inContentLanguage();
wfMessage( 'message-key' )->inLanguage( $lang );
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Output modes and escaping ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The Message class, and thus the object returned by wfMessage(), has five output modes:
</div>

* <code>plain()</code> - <span lang="en" dir="ltr" class="mw-content-ltr">returns the message text as-is; only parameters are substituted</span><ref><span lang="en" dir="ltr" class="mw-content-ltr">While using this mode to display HTML content is possible, it is recommended to use wikitext and use the parse() mode to transform it into HTML.</span></ref>
* <code>text()</code> - <span lang="en" dir="ltr" class="mw-content-ltr">transforms the message text (see <code>MessageCache::transform()</code>) which transforms all <code><nowiki>{{}}</nowiki></code> including templates and parser functions like PLURAL and GENDER, but neither escapes nor sanitizes</span>
* <code>escaped()</code> - <span lang="en" dir="ltr" class="mw-content-ltr">same as 'text', but also escapes it for use in HTML</span>
* <code>parse()</code> - <span lang="en" dir="ltr" class="mw-content-ltr">parses the message text from wikitext to HTML and sanitizes (MessageCache::parse() which calls the Parser)</span>
* <code>parseAsBlock()</code> - <span lang="en" dir="ltr" class="mw-content-ltr">the output is wrapped in a block level HTML element, if not already, similarly to OutputPage::addWikiMsg</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Remember that [[Special:MyLanguage/manual:Html.php|Html::]] functions escape everything fed into them, so use the text() format with those to avoid double escaping.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Hence the most common output format is text().</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Also, make sure to use parse() or parseAsBlock() if the message has wikitext in it, otherwise the wikitext will just be escaped and output as plain text.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
When using <code>wfMessage()</code> or {{phpi|$this->msg()}}, you should always specify an output type. <code>text()</code> is appropriate when you're outputting it through <code>addWikiText()</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Which output mode to use ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Generally speaking, the most common modes you will use are <code>->parse()</code> and <code>->text()</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You use ->parse() in most places where html markup is supported, and you use <code>->text()</code> in places where the content is going to become html escaped or html markup is not supported.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Some common cases:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting the message in the text part (third argument) of {{phpi|Html::element}} use <code>->text()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You may also consider using {{phpi|Html::rawElement()}} instead and using the <code>->parse()</code> mode.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting in text (third argument) of {{phpi|Html::rawElement()}}, you should generally use <code>->parse()</code>.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting into the attributes (second argument) of {{phpi|Html::rawElement()}} or {{phpi|Html::element()}}, use <code>->parse()</code></span>
* <span lang="en" dir="ltr" class="mw-content-ltr">If you are manually constructing html attributes, you should use <code>->escaped()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">However you should never manually construct html attributes</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">For {{phpi|$out->addWikiText()}} where <code>$out</code> is an OutputPage object use <code>->text()</code> or <code>->plain()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">However consider if you would rather use {{phpi|$out->addWikiMsg}} instead.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">For $out->addHTML() use <code>->parse()</code></span>

{{anchor|Chaining}}

<div lang="en" dir="ltr" class="mw-content-ltr">
===Method chaining===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Most Message methods return the current object, so you can conveniently call one after another to operate on an object before finally returning its text.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is called '''method chaining'''.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Here is an example:</span>

<syntaxhighlight lang="php">
wfMessage( 'key' )
	->params( 'apple' )
	->numParams( $numOfApples )
	->setContext( $context )
	->inContentLanguage()
	->parse()
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Additional methods of printing messages ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The general message function in MediaWiki is <code>wfMessage</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">'''OutputPage''' has a few methods that append directly to the generated output.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The useful ones are:</span>

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

<span lang="en" dir="ltr" class="mw-content-ltr">Both of the above parse the wikitext in the context of the current page before appending it to output buffer.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Classes extending '''ContextSource''' have a method <code>msg</code> that automatically sets the current context (language, current page etc.).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is therefore recommended to use {{phpi|$this->msg()}} for those classes, like '''special pages'''.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Here is a non-exhaustive list of such classes:</span><ref><span lang="en" dir="ltr" class="mw-content-ltr">More in general, use $this->msg() in non-static functions of IContextSource objects.</span></ref>
* CategoryViewer
* HTMLForm
* LogEventsList
* DifferenceEngine
* OutputPage
* IndexPager
* ImageHistoryList
* ApiBase
* ChangesList
* Skin

{{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">The QuickTemplate class and its subclasses (BaseTemplate) have a method named <code>msg</code> which is different from the one from ContextSource.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In these classes $this->msg() will simply output the escaped text of the message.</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">Examples of '''correct''' usage:</span>
<syntaxhighlight lang="PHP">
wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();
</syntaxhighlight>
<span lang="en" dir="ltr" class="mw-content-ltr">Examples of '''incorrect''' usage:</span>
<syntaxhighlight lang="PHP">
wfMessage( 'key', 345 )->parseInline(); # Number is not formatted correctly
$this->msg( 'key', 345 )->numParams( 234 )->plain() # Plural syntax is not converted in plain format
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Using messages in JavaScript ==
</div>
{{See also|ResourceLoader/Core_modules#mw.message|label 1=ResourceLoader/Core modules#mediaWiki.message}}
:{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This page only deals with MediaWiki core.</span> <span lang="en" dir="ltr" class="mw-content-ltr">See the specific documentation instead for the [https://github.com/wikimedia/jquery.i18n#jqueryi18n '''jquery.i18n'''] module.</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Getting the messages to the client ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">To use the messages, we need to make sure that the messages are available at client side first.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This can be done using either a ResourceLoader module (most common) or an API query from JavaScript (rare).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Using a ResourceLoader module ====
</div>
{{See also|Special:MyLanguage/Manual:$wgResourceModules|label 1=Manual:$wgResourceModules}}
: {{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This is the most common method of delivering messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You should use this unless you have a good reason not to.</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">We are going to use [[Special:MyLanguage/ResourceLoader|ResourceLoader]] to make sure that the messages are available at the client side.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For this, in your ResourceLoader modules, define the messages to be exported to the client side.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If you plan to use the <code>mw.message(…).parse()</code> to generate HTML from wikitext in interface messages, then it is important to load the [[Special:MyLanguage/ResourceLoader/Core_modules#mediawiki.jqueryMsg|mediawiki.jqueryMsg]] module.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Example (extension.json):</span> 
<syntaxhighlight lang=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"
			]
		}
	}
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Using an API query from JavaScript ====
</div>
:{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This is not a common way of loading messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You should only use this if there is a good reason why you can't use [[#Using a ResourceLoader module|the ResourceLoader module method above]].</span>}}
<span lang="en" dir="ltr" class="mw-content-ltr">You can use the following code:</span>
{{MW 1.27|and later}}
<syntaxhighlight lang="javascript">
// When: The 'mediawiki.api' module is loaded, and, the page is ready
$.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Then: Load the messages that you need (if they are not yet loaded)
    .then( function() {
        return new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] );
    } )
    // Then: Do stuff with them
    .then( doStuff );
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">To get the messages in some language other than the <code>UserLanguage</code> language, use getMessages instead of loadMessagesIfMissing, and supply the target language as the "amlang" field of the optional second parameter, like so:</span>
<syntaxhighlight lang="javascript">
// When: The 'mediawiki.api' module is loaded. No need to wait for the page to be ready.
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Then: get some messages in French (language code 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Then: Do stuff with them
    .then( doStuff );
// doStuff is a function that will receive as its first parameter an object that looks like so:
// { february: "février", january: "janvier", march: "mars" }
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">For older MediaWiki versions before 1.27, use the following:</span>
<syntaxhighlight lang="javascript">
/** @return instance of 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 );
</syntaxhighlight>


<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use of the messages ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The messages defined in the above example will be available at client side and can be accessed by <code>mw.message( 'message-key-name' )</code>.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">For example:</span>
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|text}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|text}}() );
<span lang="en" dir="ltr" class="mw-content-ltr">Note how we use jQuery <code>{{bgc|#ffb6db|text}}</code> method to escape our output properly when using mw.message <code>{{bgc|#6db6ff|text}}</code> format.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If your message contains wikitext formatting, you can instead use the following:</span>
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|append}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|parseDom}}() );
<span lang="en" dir="ltr" class="mw-content-ltr">Here we use jQuery <code>{{bgc|#ffb6db|append}}</code> method to insert the DOM nodes returned by mw.message <code>{{bgc|#6db6ff|parseDom}}</code> format.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In older code you might also encounter the following: (<code>parseDom</code> was not available until MediaWiki 1.27)</span>
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|html}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|escaped}}() );
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|html}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|parse}}() );

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">We can also pass the dynamic parameters to the message (i.e. the values for $1, $2, etc.) as shown below.</span>
<syntaxhighlight lang="javascript">
$( '<div>' ).text( mw.message( 'hello-user', username ).text() );
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">In the above examples, note that the message should be defined in an i18n file.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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⧽'.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In the case where the message key does not exists, the <code>.exists()</code> method of the returned message object will also return false instead of true.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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 [[Special:MyLanguage/Manual:Creating pages with preloaded text|preloaded text]] of a page), use:</span>
<syntaxhighlight lang="javascript">
mw.message( 'foobar' ).plain()
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Format options ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">If you don't specify the output format, mw.message just returns a Message object.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To output the message itself, you should specify an output format.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The formats are mostly the same as in PHP side:</span>

* <code>mw.message( 'foobar' ).plain()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Returns the message text as-is; only parameters are substituted.</span>
* <code>mw.message( 'foobar' ).text()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Transforms the message text (all supported <code><nowiki>{{}}</nowiki></code> blocks are replaced with transformed results).</span> <span lang="en" dir="ltr" class="mw-content-ltr">See [[#Feature support in JavaScript|#Feature support in JavaScript]] for details of what is supported.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, certain keywords (<code><nowiki>{{int:}}</nowiki></code> (but only without parameters), <code><nowiki>{{GENDER}}</nowiki></code>, <code><nowiki>{{SITENAME}}</nowiki></code> etc.) work, but tranclusion (e.g. <code><nowiki>{{MediaWiki:}}</nowiki></code>) and server-side [[Special:MyLanguage/Help:Magic words|Magic words]] such as <nowiki>{{NUMBEROFEDITS}}</nowiki> or <nowiki>{{ns:Project}}</nowiki> do not work,</span>
* <code>mw.message( 'foobar' ).escaped()</code> <span lang="en" dir="ltr" class="mw-content-ltr">HTML escaped version of <code>text</code>.</span>
* <code>mw.message( 'foobar' ).parse()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Parses the message text from wikitext to HTML.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This supports everything from <code>text</code> mode, as well as most links, and allow listed HTML.</span>
*<code>mw.message( 'foobar' ).parseDom()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Like <code>parse()</code>, but returns a jQuery collection instead of a HTML string.</span>

{{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">If the mediawiki.jqueryMsg module is not loaded, all of the above methods behave essentially like <code>plain()</code> with possible escaping.</span>}}

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">There is no equivalent of parseAsBlock.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Where necessary, wrap the output in a block element yourself.</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Parameters ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Parameters can be specified as additional arguments to <code>mw.message()</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">They can be passed as strings or as DOM nodes / jQuery collections.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Unlike in PHP, wikitext in the parameters is ''not parsed''.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Effectively, all string parameters behave like <code>plaintextParams()</code>.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">DOM/jQuery parameters can be used to achieve the equivalent of <code>rawParams()</code>.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">There is no support for other parameter formats.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Instead of <code>numParams()</code>, you must format numbers before passing them as parameters, using <code>mw.language.convertNumber()</code>.</span>
<syntaxhighlight lang="javascript">
$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() );
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Feature support in JavaScript ===
</div>
{{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">Wikitext support in JS messages requires the ''mediawiki.jqueryMsg'' module to be loaded, otherwise these features will be silently ignored.</span>}}
<span lang="en" dir="ltr" class="mw-content-ltr">JavaScript messages only support a small subset of wikitext syntax. Supported features include:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Internal links (except [[Special:MyLanguage/pipe trick|pipe trick]])</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Explicit external links (no auto-numbered and free links)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The magic words SITENAME, PAGENAME, PAGENAMEE, (in MW 1.38+) SERVERNAME</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The parser functions PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">HTML tags which are allowed in wikitext (HTML must be well-formed)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">HTML entities <code>&amp;#039;</code>, <code>&amp;quot;</code>, <code>&amp;lt;</code>, <code>&amp;gt;</code>, <code>&amp;amp;</code></span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The {{tag|nowiki|open}} tag</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Notable wikitext syntax that is '''not''' supported:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Templates</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">[[metawiki:Special:MyLanguage/Help:Interwiki_linking#Non-local_interwikis|Non-local interwiki links]]</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">All other parser functions and magic words</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Modules (for example [[Special:MyLanguage/Module:String|Module:String]])</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">All other XML-like tags (extension tags)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Bold and italic <code><nowiki>'''</nowiki></code>, <code><nowiki>''</nowiki></code> (use {{tag|b|open}}, {{tag|i|open}} instead)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Lists using <code>*</code>, <code>#</code> (use {{tag|ul|open}} or {{tag|ol|open}}, {{tag|li|open}} instead)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Definition lists / indents using <code>;</code>, <code>:</code> (use {{tag|dl|open}}, {{tag|dt|open}}, {{tag|dd|open}} instead)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Multiple paragraphs (use {{tag|p|open}} instead)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Self-closing HTML tags</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Comments</span> <syntaxhighlight lang=html inline><!-- --></syntaxhighlight>
* <span lang="en" dir="ltr" class="mw-content-ltr">Some types of nesting (e.g. <syntaxhighlight lang="html" inline>{{PLURAL:$1|<strong>$1</strong>}}</syntaxhighlight>)</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The [[translatewiki:Template:Doc-jqueryMsg|doc-jqueryMsg template]] can be used to [[Special:MyLanguage/Help:System message#Message documentation|document]] such messages, to let translators know which wikitext restrictions apply.
</div>

=== mw.msg ===
<div lang="en" dir="ltr" class="mw-content-ltr">
The <code>mw.msg()</code> function is commonly used as a shortcut for <code>mw.message().text()</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Exporting messages through ResourceLoader callbacks ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">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 [[ResourceLoader/Package files#Generated_content|package files callback]] in your ResourceLoader module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">When you do this, take care to use {{phpi|$context->msg()}}, because using <code>wfMessage()</code> will [[Special:MyLanguage/ResourceLoader/Package files#Common pitfall: using i18n messages in generated content callbacks|cause errors]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Using messages in Lua ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Modules written in Lua using {{ll|Extension:Scribunto|Scribunto}} run similarly to templates and have access to MediaWiki messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The MediaWiki Lua library includes the mw.message class for processing messages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Refer to the full [[Special:MyLanguage/Extension:Scribunto/Lua reference manual#Message library|Lua message library]] documentation for the full API.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Here is a simple example:</span>

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

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- This ensures number localization
	-- Show the message in the language of the wiki. frame:preprocess expands the {{plural}} clause.
	return frame:preprocess( nmembersMsg:plain() )
end

return p
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Notes about gender, grammar, plural ==
</div>
: <span lang="en" dir="ltr" class="mw-content-ltr">See also [[#Switches in messages…|#Switches in messages…]]; the syntax itself is documented at [[Special:MyLanguage/Help:Magic words#Localization|Help:Magic words#Localization]] and related.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In general, GENDER, GRAMMAR and PLURAL magic words work identically in both PHP and JavaScript sides.</span>

# <span lang="en" dir="ltr" class="mw-content-ltr">You must use <code>text</code>, <code>escaped</code>, <code>parse</code> or <code>parseAsBlock</code> [[#Output modes and escaping|output formats]] for them to work.</span>
#* <span lang="en" dir="ltr" class="mw-content-ltr">In PHP, you can use wfMessage or <code>[[#Additional methods of printing messages|$this->msg]]</code>.</span>
#* <span lang="en" dir="ltr" class="mw-content-ltr">In JavaScript, make sure your resource loader module depends on <code>jqueryMsg</code> (see [[#Using messages in JavaScript|#Using messages in JavaScript]]).</span>
# <span lang="en" dir="ltr" class="mw-content-ltr">You need to pass the relevant parameter as normal parameter to the message.</span>
#* <span lang="en" dir="ltr" class="mw-content-ltr">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 ([[#GENDER in JavaScript|see below]]).</span>
#* <span lang="en" dir="ltr" class="mw-content-ltr">For enabling plural and correct number localization in PHP, you need to use <code>numParams</code> for the number, see also [[#Chaining|#Chaining]].</span>
#* <span lang="en" dir="ltr" class="mw-content-ltr">For enabling plural and correct number localization in JavaScript, you need to use <code>mw.language.convertNumber</code> for the number</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== PLURAL syntax example ===
</div>
<syntaxhighlight lang="PHP">
# Simple plural
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'
</syntaxhighlight>

{{anchor|JavaScript examples}}
<div lang="en" dir="ltr" class="mw-content-ltr">
=== GENDER in JavaScript ===
</div>
{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This needs explicit <code>jqueryMsg</code>, see [[#Using messages in JavaScript|#Using messages in JavaScript]].</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">If you have a message, say, <code><nowiki>"message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article"</nowiki></code>, in JavaScript, you can use it as given below:</span>

<syntaxhighlight lang=javascript>
mw.message( 'message-key-gender-foo', 'male' ).text(); // returns 'he created an article'
mw.message( 'message-key-gender-foo', 'female' ).text(); // returns 'she created an article'
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // returns 'they created an article'
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">Instead of passing the gender directly, we can pass any "User-like" object with a gender option.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, the current user object <code>mw.user</code>.</span>

<syntaxhighlight lang=javascript>
var user = mw.user; // current user
mw.message( 'message-key-gender-foo', user ).text(); // The message returned will be based on the gender of the current user.
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">If the gender passed is invalid or unknown, the gender neutral form will be used as defined for each language.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Pass <code>'unknown'</code> if you intentionally want the neutral form.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Finally, if you want to use the gender of the current user, you can pass an empty string:</span>
<syntaxhighlight lang=javascript>
// the following line illustrates the message content, you can run this snippet on developer console
mw.messages.set( 'message-key-gender-foo', '{{GENDER:$1|male|female|unknown}}' );
mw.user.options.values.gender = 'female'; // temporarily manipulate your gender preference
mw.message( 'message-key-gender-foo', '' ).text(); // return value depends on your gender preference
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== PLURAL in JavaScript ===
</div>
{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This needs explicit <code>jqueryMsg</code>, see [[#Using messages in JavaScript|#Using messages in JavaScript]].</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">If you have a message, say <code><nowiki> 'message-key-plural-foo' => 'There {{PLURAL:$1|is|are}} $1 {{PLURAL:$1|item|items}}' </nowiki></code> , in JavaScript, you can use it as given below:</span>

<syntaxhighlight lang=javascript>
mw.message( 'message-key-plural-foo', count ).text();
// returns 'There is 1 item' if count = 1
// returns 'There are 6 items' if count = 6
</syntaxhighlight>

{{Anchor|Deprecated wfMsg* functions}}
<div lang="en" dir="ltr" class="mw-content-ltr">
== Help with replacing deprecated wfMsg* functions ==
</div>
{{Note|1=<span lang="en" dir="ltr" class="mw-content-ltr">These functions were removed [[gerrit:262333|starting with MediaWiki 1.27 LTS]].</span>|2=gotcha}}

<span lang="en" dir="ltr" class="mw-content-ltr">The code using these functions often has incorrect escaping and other code quality issues, so it's also recommended to</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">replace all Xml:: functions with their Html:: equivalents, which make it easier to do the right thing;</span><ref><span lang="en" dir="ltr" class="mw-content-ltr">For instance Xml::tags() doesn't escape.</span></ref>
* <span lang="en" dir="ltr" class="mw-content-ltr">where possible, avoid globals and use <code>msg()</code> (see [[#Additional methods of printing messages|above]]);</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">replace <code>htmlspecialchars()</code> with <code>->escaped()</code> where appropriate.</span>

<!-- TODO FIXME: add some other common usage cases here, such as wfMsg... -->
{| class="wikitable"
! width="490px" | <span lang="en" dir="ltr" class="mw-content-ltr">Code change</span>
! <span lang="en" dir="ltr" class="mw-content-ltr">Description</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsg( 'key' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key' )->text();}}
| &nbsp;
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgExt( 'key', SOME_FORMAT, 'apple' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">The second parameter specifies the output mode, usually expressed as an array like <code>array( 'escape' )</code> but sometimes just like <code>'escape'</code>: it needs to be replaced according to [[#Output modes and escaping|#Output modes and escaping]], like <code>->escaped()</code>.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgExt( 'key', array( 'parse' ), 'apple' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key', 'apple' )->parseAsBlock();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Use full parsing, and wrap the output in block-level HTML tags.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgExt( 'key', array( 'parseinline' ), 'apple' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key', 'apple' )->parse();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Use full parsing.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Parseinline is used because it is more useful when pre-building HTML.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In normal use it is better to use <nowiki>OutputPage::(add|wrap)WikiMsg.</nowiki></span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key', 'apple', 'pear' )->text();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Places where HTML cannot be used.</span> <span lang="en" dir="ltr" class="mw-content-ltr">{{-transformation is done.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of</span>
:{{phpi|wfMsgHtml( 'key', 'apple' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key' )->rawParams( 'apple' )->escaped();}}
| <span lang="en" dir="ltr" class="mw-content-ltr"><code>wfMsgHtml</code> does not escape parameters: to get the same result you need to use rawParams; check that the parameter really is safe for HTML output.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If the message is then output as HTML, you must use <code>escaped()</code> for [[Special:MyLanguage/Security for developers|security]]: it will escape the parameters too and that's not always wanted, although it doesn't matter e.g. when the parameter is a number.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgForContent( 'key' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key' )->inContentLanguage()->text();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Get a message in the wiki's content language</span> ({{ll|Manual:$wgLanguageCode|$wgLanguageCode}}).
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgForContentNoTrans( 'key' );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key' )->inContentLanguage()->plain();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Get a message in the wiki's content language ({{ll|Manual:$wgLanguageCode|$wgLanguageCode}}) but don't transform the message.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfEmptyMsg( 'key', $message {{=}} wfMsgForContent( 'key' ) );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:{{phpi|wfMessage( 'key' )->inContentLanguage()->isBlank();}}
| <span lang="en" dir="ltr" class="mw-content-ltr">Checks if the 'key' message in the wiki's content language is empty.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Often, <code>isDisabled()</code> is a more appropriate check and should be used instead.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:{{phpi|wfMsgReal( $error['message'], $error['params'] );}}
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:<code>?</code>
| <span lang="en" dir="ltr" class="mw-content-ltr">There is no simple replacement, depends on parameters.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Should never have been used in the first place.</span>
|-
| <span lang="en" dir="ltr" class="mw-content-ltr">Instead of:</span>
:<code>wfMsgGetKey</code>
<span lang="en" dir="ltr" class="mw-content-ltr">write:</span>
:<code>?</code>
| <span lang="en" dir="ltr" class="mw-content-ltr">There is no simple replacement, depends on parameters.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Should never have been used in the first place.</span>
|}


<div lang="en" dir="ltr" class="mw-content-ltr">
== See also ==
</div>
* {{ll|API:Allmessages}}
* {{ll|Help:HTML_in_wikitext}}
* [https://doc.wikimedia.org/mediawiki-core/master/php/classMessage.html <span lang="en" dir="ltr" class="mw-content-ltr">Message class documentation</span>]

<div lang="en" dir="ltr" class="mw-content-ltr">
==Notes==
</div>
<references/>
{{Parser functions nav}}

[[Category:MediaWiki code{{#translation:}}]]
[[Category:Localisation{{#translation:}}]]