View source for Manual:Messages API

<languages/>
{{i18n navigation}}
<translate><!--T:1--> {{<tvar name=1>ll|Help:System message</tvar>|MediaWiki messages}} can be used in the code through the <tvar name=2>Message</tvar> class and its associated methods.</translate>

{{ambox
|text = <translate><!--T:20--> While the examples throughout this document make use of the global function <tvar name=1><code>wfMessage()</code></tvar>, in most cases it is best not to use this global function.</translate> <translate><!--T:24--> Instead, you should use an object that provides a <tvar name=1>{{ll|Manual:RequestContext.php|RequestContext}}</tvar>, and call <tvar name=2>{{phpi|$context->msg()}}</tvar> on it.</translate> <translate><!--T:25--> In many classes, you can use <tvar name=1>{{phpi|$this->msg()}}</tvar>.</translate>
}}

<translate>
==Message parameters== <!--T:26-->
</translate>
<translate><!--T:27--> Some messages take parameters.</translate>
<translate><!--T:28--> They are represented by <tvar name=1><code>$1</code></tvar>, <tvar name=2><code>$2</code></tvar>, <tvar name=3><code>$3</code></tvar>, … in the (static) message texts, and replaced at run time.</translate>
<translate><!--T:29--> 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.</translate>
<translate><!--T:30--> They can be of arbitrary complexity.</translate>

<translate>
<!--T:31-->
The list of parameters defined for each specific message is placed in special file "<tvar name=1>qqq.json</tvar>" located in "<tvar name=2>languages/</tvar>" folder of MediaWiki - read more in [[<tvar name=3>Special:MyLanguage/Help:System message#Message documentation</tvar>|Message documentation]].
</translate>

<translate><!--T:32--> It's preferable to use whole words with the PLURAL, GENDER, and GRAMMAR magic words.</translate>
<translate><!--T:33--> For example, <code><nowiki>{{PLURAL:$1|subpage|subpages}}</nowiki></code> is better than <code><nowiki>sub{{PLURAL:$1|page|pages}}</nowiki></code>.</translate>
<translate><!--T:34--> It makes searching easier.</translate>

<translate>
=== Referring to other messages === <!--T:298-->
</translate>
<translate><!--T:299--> 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.</translate>
<translate><!--T:300--> To do so, you may use the following syntax:</translate>

* <code><nowiki>{{int:X}}</nowiki></code> – <translate><!--T:301--> to use the sub-message in interface language.</translate> <translate><!--T:302--> This is often used when referring to form buttons or site navigation, e.g. <tvar name=1>[[MediaWiki:Showpreview|showpreview]]</tvar>.</translate>
* <code><nowiki>{{MediaWiki:Y}}</nowiki></code> – <translate><!--T:303--> to use the sub-message in content language.</translate> <translate><!--T:304--> This is used when the sub-message defines a translatable name of a local page, e.g. <tvar name=1>[[MediaWiki:Mainpage|mainpage]]</tvar>, <tvar name=2>[[MediaWiki:Grouppage-sysop|grouppage-sysop]]</tvar>, <tvar name=3>[[MediaWiki:Policy-url|policy-url]]</tvar>.</translate>
* <code><nowiki>{{#Special:Z}}</nowiki></code> – <translate><!--T:305--> to use the name of a special page in content language.</translate>

<translate>
<!--T:306-->
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.

<!--T:307-->
Example:
</translate>

<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>

<translate>
===Switches in messages…=== <!--T:35-->
</translate>
<translate><!--T:36--> Parameters values at times influence the exact wording, or grammatical variations in messages.</translate>
<translate><!--T:37--> We don't resort to ugly constructs like "<tvar name=2>$1 (sub)page(s) of his/her userpage</tvar>", because these are poor for users and we can do better.</translate>
<translate><!--T:38--> Instead, we make switches that are parsed according to values that will be known at run time.</translate>
<translate><!--T:39--> 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.</translate>
<!--SIC! the link is meant to go to the disambiguation page. The biggest possible overview is desired. -->
<translate><!--T:40--> This resembles the way <tvar name=1>{{ll|parser functions}}</tvar> are called in MediaWiki.</translate>
<translate><!--T:41--> Several types of switches are available.</translate>
'''<translate><!--T:42--> These only work if you do full parsing, or <tvar name=1><code><nowiki>{{</nowiki></code></tvar>-transformation, for the messages.</translate>'''

<translate>
====…on numbers via PLURAL==== <!--T:43-->
</translate>

<translate><!--T:44--> MediaWiki supports plurals, which makes for a nicer-looking product.</translate>
<translate><!--T:45--> For example:</translate>

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

<translate>
<!--T:46-->
If there is an explicit plural form to be given for a specific number, it is possible with the following syntax:
</translate>

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

<translate>
=====Be aware of PLURAL use on ''all'' numbers===== <!--T:47-->
</translate>
{{See also|translatewiki:Plural|Help:Magic words#plural}}

<translate><!--T:49--> 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.</translate>
<translate><!--T:50--> 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.''</translate>

<translate><!--T:51--> Do not try to supply three different messages for cases like "no items counted", "one item counted", "more items counted".</translate>
<translate><!--T:52--> 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.</translate>

<translate><!--T:53--> Always include the number as a parameter if possible.</translate>
<translate><!--T:54--> Always add <tvar name=1><code><nowiki>{{PLURAL:}}</nowiki></code></tvar> syntax to the source messages if possible, even if it makes no sense in English.</translate>
<translate><!--T:55--> The syntax guides translators.</translate>

<translate>
<!--T:56-->
Fractional numbers are supported, but the plural rules may not be complete.

=====Pass the number of list items as parameters to messages talking about lists===== <!--T:57-->
</translate>
<translate><!--T:58--> Don't assume that there's only singular and plural.</translate>
<translate><!--T:59--> Many languages have more than two forms, which depend on the actual number used and they have to use [[<tvar name=1>#…on use context inside sentences via GRAMMAR</tvar>|grammar]] varying with the number of list items when expressing what is listed in a list visible to readers.</translate>
<translate><!--T:60--> Thus, whenever your code computes a list, include <tvar name=1><code>count( $list )</code></tvar> as parameter to headlines, lead-ins, footers and other messages about the list, even if the count is not used in English.</translate>
<translate><!--T:61--> 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.</translate>

<translate>
====…on user names via GENDER==== <!--T:62-->
</translate>

<!-- 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>

<translate><!--T:63--> 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.</translate>
<translate><!--T:64--> If it is likely that <tvar name=1>GENDER</tvar> will be used in translations for languages with gender inflections, add it explicitly in the English language source message.</translate>

<translate>
<!--T:65-->
If you directly address the currently logged-in user, leave the user name as parameter empty:
</translate>

<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}}
<translate>
<!--T:66-->
If you include the user name into the message (e.g. <tvar name=1><code>{{int|Notification-compact-header-flow-thank}}</code></tvar>), consider passing it through <tvar name=2><code>wfEscapeWikitext()</code></tvar> first, to ensure that characters like <tvar name=3><code>*</code></tvar> or <tvar name=4><code>;</code></tvar> are not interpreted.

=====Users have grammatical genders===== <!--T:67-->
</translate>
{{See also|translatewiki:Gender|Help:Magic words#gender}}

<translate><!--T:69--> 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. </translate>
<translate><!--T:70--> Thus languages having to, or wanting to, use proper gender dependent grammar, can do so. </translate>
<translate><!--T:71--> 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.</translate>

<translate>
<!--T:72-->
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.

====…on use context inside sentences via GRAMMAR==== <!--T:73-->
</translate>

<translate><!--T:74--> Grammatical transformations for {{Q|171263|agglutinative language}} is also available.</translate>
<translate><!--T:75--> For example for Finnish, where it was an absolute necessity to make language files site-independent, ''i.e.'' to remove the Wikipedia references.</translate>
<translate><!--T:76--> In Finnish, "<tvar name=1>about Wikipedia</tvar>" becomes "<tvar name=2>Tietoja Wikipediasta</tvar>" and "<tvar name=3>you can upload it to Wikipedia</tvar>" becomes "<tvar name=4>Voit tallentaa tiedoston Wikipediaan</tvar>".</translate>
<translate><!--T:77--> Suffixes are added depending on how the word is used, plus minor modifications to the base.</translate>
<translate><!--T:78--> 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.</translate>

<translate><!--T:79--> MediaWiki has grammatical transformation functions for over 20 languages.</translate>
<translate><!--T:80--> 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.</translate>

<translate><!--T:81--> Even before MediaWiki had arbitrary grammatical transformation, it had a nominative/genitive distinction for month names.</translate>
<translate><!--T:82--> This distinction is necessary for some languages if you wish to substitute month names into sentences.</translate>

<translate>
===Filtering special characters in parameters and messages=== <!--T:83--> 

<!--T:84-->
The other (much simpler) issue with parameter substitution is HTML escaping. Despite being much simpler, MediaWiki does a pretty poor job of it.

== Using messages in PHP == <!--T:3-->
</translate>
{{warning|1=<translate><!--T:8--> Make sure you always use one of the [[<tvar name=1>#Output modes and escaping</tvar>|output modes]] mentioned below</translate>}}

<translate>
<!--T:9-->
Here is a simple example:
</translate>

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

<translate><!--T:10--> <tvar name=1><code>wfMessage()</code></tvar> is a global function which acts as a wrapper for the Message class, creating a Message object.</translate>
<translate><!--T:11--> This example then invokes Message method <tvar name=1><code>text()</code></tvar> which fetches the text of the <tvar name=2><code>submit</code></tvar> message in the current language, performs certain language transformations (such as gender and plural), and returns the unescaped message text.</translate>

<translate>
<!--T:12-->
Here is a more complex example using a message that takes a count and supports linguistic plural handling:
</translate>

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

<translate>
<!--T:336-->
Don't use the <tvar name=1><code>formatnum</code></tvar> magic word in messages. Always format the numbers in code.

<!--T:13-->
The following sections explain the code.

===Parameters=== <!--T:14-->

<!--T:15-->
Given a message like the following:
</translate>

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

<translate>
<!--T:16-->
You pass parameters to messages that need them in several ways:
</translate>

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

<translate>
<!--T:17-->
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'':
</translate>

<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>
: <translate><!--T:85--> Normal message substitution parameter.</translate>
; <code>rawParams()</code>
: <translate><!--T:86--> 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).</translate> <translate><!--T:87--> Make sure you escape them properly yourself.</translate>
; <code>plaintextParams()</code>
: <translate><!--T:88--> Like <tvar name=1><code>rawParams()</code></tvar>, but does escaping.</translate> <translate><!--T:89--> It is useful when you pass user input that may contain wikitext that should not be parsed.</translate>

<translate><!--T:90--> Each function from the second group formats the value in a specific way before the substitution.</translate> 
<translate><!--T:91--> <tvar name=1><code>numParams()</code></tvar> must be used if the message uses <tvar name=2><code><nowiki>{{PLURAL:}}</nowiki></code></tvar>.</translate>
<translate><!--T:92--> In some cases you might not want to use it even though you have a number, for example a revision ID.</translate>
<translate><!--T:93--> The other functions correspond to Language functions <tvar name=1><code>formatDuration</code></tvar>, <tvar name=2><code>formatExpiry</code></tvar>, <tvar name=3><code>formatTimePeriod</code></tvar>, <tvar name=4><code>formatSize</code></tvar> and <tvar name=5><code>formatBitrate</code></tvar>, and are just shorthands for calling them directly.</translate>

<translate>
===Language=== <!--T:94-->
</translate>
<translate><!--T:95--> 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.</translate>
<translate><!--T:96--> In the latter case you can use either a language code or a language object.</translate>
<translate><!--T:97--> 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.</translate>

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

<translate>
=== Output modes and escaping === <!--T:4-->

<!--T:98-->
The Message class, and thus the object returned by wfMessage(), has five output modes:
</translate>

* <code>plain()</code> – <translate><!--T:119--> returns the message text as-is; only parameters are substituted</translate><ref><translate><!--T:120--> 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.</translate></ref>
* <code>text()</code> – <translate><!--T:121--> transforms the message text (see <tvar name=1><code>MessageCache::transform()</code></tvar>) which transforms all <tvar name=2><code><nowiki>{{}}</nowiki></code></tvar> including templates and parser functions like <tvar name=3>PLURAL</tvar> and <tvar name=4>GENDER</tvar>, but neither escapes nor sanitizes</translate>
* <code>escaped()</code> – <translate><!--T:122--> same as 'text', but also escapes it for use in HTML</translate>
* <code>parse()</code> – <translate><!--T:123--> parses the message text from wikitext to HTML and sanitizes (<tvar name=1>MessageCache::parse()</tvar> which calls the Parser)</translate>
* <code>parseAsBlock()</code> – <translate><!--T:124--> the output is wrapped in a block level HTML element, if not already, similarly to <tvar name=1>OutputPage::addWikiMsg</tvar></translate>

<translate><!--T:125--> Remember that [[<tvar name=1>Special:MyLanguage/manual:Html.php</tvar>|Html::]] functions escape everything fed into them, so use the <tvar name=2>text()</tvar> format with those to avoid double escaping.</translate>
<translate><!--T:126--> Hence the most common output format is <tvar name=1>text()</tvar>.</translate>
<translate><!--T:127--> Also, make sure to use <tvar name=1>parse()</tvar> or <tvar name=2>parseAsBlock()</tvar> if the message has wikitext in it, otherwise the wikitext will just be escaped and output as plain text.</translate>

<translate><!--T:128--> When using <tvar name=1><code>wfMessage()</code></tvar> or <tvar name=2>{{phpi|$this->msg()}}</tvar>, you should always specify an output type.</translate>
<translate><!--T:340--> <tvar name=3><code>text()</code></tvar> is appropriate when you're outputting it through <tvar name=4><code>addWikiText()</code></tvar>.</translate>

<translate>
==== Which output mode to use ==== <!--T:99-->
</translate>
<translate><!--T:129--> Generally speaking, the most common modes you will use are <tvar name=1><code>->parse()</code></tvar> and <tvar name=2><code>->text()</code></tvar>.</translate>
<translate><!--T:130--> You use <tvar name=1>->parse()</tvar> in most places where HTML markup is supported, and you use <tvar name=2><code>->text()</code></tvar> in places where the content is going to become HTML escaped or HTML markup is not supported.</translate>

<translate><!--T:131--> Some common cases:</translate>

* <translate><!--T:132--> If you are putting the message in the text part (third argument) of <tvar name=1>{{phpi|Html::element}}</tvar> use <tvar name=2><code>->text()</code></tvar>.</translate> <translate><!--T:133--> You may also consider using <tvar name=1>{{phpi|Html::rawElement()}}</tvar> instead and using the <tvar name=2><code>->parse()</code></tvar> mode.</translate>
* <translate><!--T:134--> If you are putting in text (third argument) of <tvar name=1>{{phpi|Html::rawElement()}}</tvar>, you should generally use <tvar name=2><code>->parse()</code></tvar>.</translate>
* <translate><!--T:135--> If you are putting into the attributes (second argument) of <tvar name=1>{{phpi|Html::rawElement()}}</tvar> or <tvar name=2>{{phpi|Html::element()}}</tvar>, use <tvar name=3><code>->parse()</code></tvar></translate>
* <translate><!--T:136--> If you are manually constructing HTML attributes, you should use <tvar name=1><code>->escaped()</code></tvar>.</translate> <translate><!--T:137--> However you should never manually construct HTML attributes</translate>
* <translate><!--T:138--> For <tvar name=1>{{phpi|$out->addWikiText()}}</tvar> where <tvar name=2><code>$out</code></tvar> is an OutputPage object use <tvar name=3><code>->text()</code></tvar> or <tvar name=4><code>->plain()</code></tvar>.</translate> <translate><!--T:139--> However consider if you would rather use <tvar name=1>{{phpi|$out->addWikiMsg}}</tvar> instead.</translate>
* <translate><!--T:140--> For <tvar name=1>$out->addHTML()</tvar> use <tvar name=2><code>->parse()</code></tvar></translate>

{{anchor|Chaining}}
<translate>

===Method chaining=== <!--T:5-->
</translate>
<translate><!--T:141--> 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.</translate>
<translate><!--T:142--> This is called '''method chaining'''.</translate>
<translate><!--T:143--> Here is an example:</translate>

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

<translate>
=== Additional methods of printing messages === <!--T:6-->
</translate>
<translate><!--T:144--> The general message function in MediaWiki is <tvar name=1><code>wfMessage</code></tvar>.</translate>
<translate><!--T:145--> 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.</translate>

<translate><!--T:146--> '''<tvar name=1>OutputPage</tvar>''' has a few methods that append directly to the generated output.</translate>
<translate><!--T:147--> The useful ones are:</translate>

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

<translate><!--T:148--> Both of the above parse the wikitext in the context of the current page before appending it to output buffer.</translate>

<translate><!--T:149--> Classes extending '''<tvar name=1>ContextSource</tvar>''' have a method <tvar name=2><code>msg</code></tvar> that automatically sets the current context (language, current page etc.).</translate>
<translate><!--T:150--> It is therefore recommended to use <tvar name=1>{{phpi|$this->msg()}}</tvar> for those classes, like '''special pages'''.</translate>
<translate><!--T:151--> Here is a non-exhaustive list of such classes:</translate><ref><translate><!--T:152--> More in general, use <tvar name=1>$this->msg()</tvar> in non-static functions of <tvar name=2>IContextSource</tvar> objects.</translate></ref>
* CategoryViewer
* HTMLForm
* LogEventsList
* DifferenceEngine
* OutputPage
* IndexPager
* ImageHistoryList
* ApiBase
* ChangesList
* Skin

{{warning|1=<translate><!--T:153--> The <tvar name=1>QuickTemplate</tvar> class and its subclasses (<tvar name=2>BaseTemplate</tvar>) have a method named <tvar name=3><code>msg</code></tvar> which is different from the one from <tvar name=4>ContextSource</tvar>.</translate>
<translate><!--T:154--> In these classes <tvar name=1>$this->msg()</tvar> will simply output the escaped text of the message.</translate>}}

<translate><!--T:155--> Examples of '''correct''' usage:</translate>
<syntaxhighlight lang="PHP">
wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();
</syntaxhighlight>
<translate><!--T:156--> Examples of '''incorrect''' usage:</translate>
<syntaxhighlight lang="PHP">
wfMessage( 'key', 345 )->parseInline(); # <translate nowrap><!--T:313--> Number is not formatted correctly</translate>
$this->msg( 'key', 345 )->numParams( 234 )->plain() # <translate nowrap><!--T:314--> Plural syntax is not converted in plain format</translate>
</syntaxhighlight>

<translate>
== Using messages in JavaScript == <!--T:7-->
</translate>
{{See also|ResourceLoader/Core_modules#mw.message|label 1=ResourceLoader/Core modules#mediaWiki.message}}
:{{note|1=<translate><!--T:158--> This page only deals with MediaWiki core.</translate> <translate><!--T:159--> See the specific documentation instead for the <tvar name=1>[https://github.com/wikimedia/jquery.i18n#jqueryi18n '''jquery.i18n''']</tvar> module.</translate>}}

<translate>
=== Getting the messages to the client === <!--T:100-->
</translate>
<translate><!--T:160--> To use the messages, we need to make sure that the messages are available at client side first.</translate>
<translate><!--T:161--> This can be done using either a ResourceLoader module (most common) or an API query from JavaScript (rare).</translate>

<translate>
==== Using a ResourceLoader module ==== <!--T:101-->
</translate>
{{See also|Special:MyLanguage/Manual:$wgResourceModules|label 1=Manual:$wgResourceModules}}
: {{note|1=<translate><!--T:163--> This is the most common method of delivering messages.</translate> <translate><!--T:164--> You should use this unless you have a good reason not to.</translate>}}

<translate><!--T:165--> We are going to use <tvar name=1>[[Special:MyLanguage/ResourceLoader|ResourceLoader]]</tvar> to make sure that the messages are available at the client side.</translate>
<translate><!--T:166--> For this, in your ResourceLoader modules, define the messages to be exported to the client side.</translate>

<translate><!--T:167--> If you plan to use the <tvar name=1><code>mw.message(…).parse()</code></tvar> to generate HTML from wikitext in interface messages, then it is important to load the [[<tvar name=2>Special:MyLanguage/ResourceLoader/Core_modules#mediawiki.jqueryMsg</tvar>|mediawiki.jqueryMsg]] module.</translate>

<translate><!--T:168--> Example (<tvar name=1>extension.json</tvar>):</translate> 
<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>

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

<translate><!--T:172--> To get the messages in some language other than the <tvar name=1><code>UserLanguage</code></tvar> language, use getMessages instead of loadMessagesIfMissing, and supply the target language as the "amlang" field of the optional second parameter, like so:</translate>
<syntaxhighlight lang="javascript">
// <translate nowrap><!--T:318--> When: The '<tvar name=1>mediawiki.api</tvar>' module is loaded. No need to wait for the page to be ready.</translate>
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // <translate nowrap><!--T:319--> Then: get some messages in <tvar name=1>French</tvar> (language code '<tvar name=2>fr</tvar>')</translate>
    .then( () => new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' } ) )
    // <translate nowrap><!--T:320--> Then: Do stuff with them</translate>
    .then( doStuff );
// <translate nowrap><!--T:321--> doStuff is a function that will receive as its first parameter an object that looks like so:</translate>
// { february: "février", january: "janvier", march: "mars" }
</syntaxhighlight>
<translate>
=== Use of the messages === <!--T:103-->
</translate>
<translate><!--T:174--> The messages defined in the above example will be available at client side and can be accessed by <tvar name=1><code>mw.message( 'message-key-name' )</code></tvar>.</translate>

<translate><!--T:175--> For example:</translate>
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|text}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|text}}() );
<translate><!--T:176--> Note how we use jQuery <tvar name=1><code>{{bgc|#ffb6db|text}}</code></tvar> method to escape our output properly when using mw.message <tvar name=2><code>{{bgc|#6db6ff|text}}</code></tvar> format.</translate>

<translate><!--T:177--> If your message contains wikitext formatting, you can instead use the following:</translate>
 $( {{code-string|'&lt;div>'}} ).{{bgc|#ffb6db|append}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|parseDom}}() );
<translate><!--T:178--> Here we use jQuery <tvar name=1><code>{{bgc|#ffb6db|append}}</code></tvar> method to insert the DOM nodes returned by mw.message <tvar name=2><code>{{bgc|#6db6ff|parseDom}}</code></tvar> format.</translate>

<translate><!--T:179--> In older code you might also encounter the following: (<tvar name=1><code>parseDom</code></tvar> was not available until MediaWiki 1.27)</translate>
 $( {{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}}() );

<translate><!--T:180--> 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.</translate>

<translate><!--T:181--> We can also pass the dynamic parameters to the message (i.e. the values for $1, $2, etc.) as shown below.</translate>
<syntaxhighlight lang="javascript">
$( '<div>' ).text( mw.message( 'hello-user', username ).text() );
</syntaxhighlight>

<translate><!--T:182--> In the above examples, note that the message should be defined in an i18n file.</translate>
<translate><!--T:183--> 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 <tvar name=1><code>⧼message-key-foo⧽</code></tvar>.</translate>
<translate><!--T:184--> In older versions of MediaWiki, the message key was returned in ASCII angle brackets, like <tvar name=1><code>&lt;message-key-foo&gt;</code></tvar>, and this could generate invalid or fake HTML elements.</translate>
<translate><!--T:185--> In the case where the message key does not exists, the <tvar name=1><code>.exists()</code></tvar> method of the returned message object will also return false instead of true.</translate>

<translate><!--T:186--> 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 [[<tvar name=1>Special:MyLanguage/Manual:Creating pages with preloaded text</tvar>|preloaded text]] of a page), use:</translate>
<syntaxhighlight lang="javascript">
mw.message( 'foobar' ).plain()
</syntaxhighlight>

<translate>
==== Format options ==== <!--T:104-->
</translate>
<translate><!--T:187--> If you don't specify the output format, <tvar name=1>mw.message</tvar> just returns a <tvar name=2>Message</tvar> object.</translate>
<translate><!--T:188--> To output the message itself, you should specify an output format.</translate>
<translate><!--T:189--> The formats are mostly the same as in PHP side:</translate>

* <code>mw.message( 'foobar' ).plain()</code> <translate><!--T:190--> Returns the message text as-is; only parameters are substituted.</translate>
* <code>mw.message( 'foobar' ).text()</code> <translate><!--T:191--> Transforms the message text (all supported <tvar name=1><code><nowiki>{{}}</nowiki></code></tvar> blocks are replaced with transformed results).</translate> <translate><!--T:192--> See [[<tvar name=1>#Feature support in JavaScript</tvar>|#Feature support in JavaScript]] for details of what is supported.</translate> <translate><!--T:193--> For example, certain keywords (<tvar name=1><code><nowiki>{{int:}}</nowiki></code></tvar>, <tvar name=2><code><nowiki>{{GENDER}}</nowiki></code></tvar>, <tvar name=3><code><nowiki>{{SITENAME}}</nowiki></code></tvar> etc.) work without parameters, but tranclusion (e.g. <tvar name=4><code><nowiki>{{MediaWiki:}}</nowiki></code></tvar>) and server-side [[<tvar name=5>Special:MyLanguage/Help:Magic words</tvar>|Magic words]] such as <tvar name=6><nowiki>{{NUMBEROFEDITS}}</nowiki></tvar> or <tvar name=7><nowiki>{{ns:Project}}</nowiki></tvar> do not work,</translate>
* <code>mw.message( 'foobar' ).escaped()</code> <translate><!--T:194--> HTML escaped version of <tvar name=1><code>text</code></tvar>.</translate>
* <code>mw.message( 'foobar' ).parse()</code> <translate><!--T:195--> Parses the message text from wikitext to HTML.</translate> <translate><!--T:196--> This supports everything from <tvar name=1><code>text</code></tvar> mode, as well as most links, and allow listed HTML.</translate>
*<code>mw.message( 'foobar' ).parseDom()</code> <translate><!--T:197--> Like <tvar name=1><code>parse()</code></tvar>, but returns a jQuery collection instead of a HTML string.</translate>

{{warning|1=<translate><!--T:198--> If the mediawiki.jqueryMsg module is not loaded, all of the above methods behave essentially like <tvar name=1><code>plain()</code></tvar> with possible escaping.</translate>}}

{{note|1=<translate><!--T:199--> There is no equivalent of parseAsBlock.</translate> <translate><!--T:200--> Where necessary, wrap the output in a block element yourself.</translate>}}

<translate>
==== Parameters ==== <!--T:105-->
</translate>
<translate><!--T:201--> Parameters can be specified as additional arguments to <tvar name=1><code>mw.message()</code></tvar>.</translate>
<translate><!--T:202--> They can be passed as strings or as DOM nodes / jQuery collections.</translate>

<translate><!--T:203--> Unlike in PHP, wikitext in the parameters is ''not parsed''.</translate>
<translate><!--T:204--> Effectively, all string parameters behave like <tvar name=1><code>plaintextParams()</code></tvar>.</translate>

<translate><!--T:205--> DOM/jQuery parameters can be used to achieve the equivalent of <tvar name=1><code>rawParams()</code></tvar>.</translate>

<translate><!--T:206--> There is no support for other parameter formats.</translate>
<translate><!--T:338--> Don't use the <tvar name=1><code>formatnum</code></tvar> magic word in messages.</translate>
<translate><!--T:337--> Always format the numbers in code.</translate>
<translate><!--T:207--> In JavaScript, instead of <tvar name=1><code>numParams()</code></tvar>, you must format numbers before passing them as parameters, using <tvar name=2><code>mw.language.convertNumber()</code></tvar>.</translate>
<syntaxhighlight lang="javascript">
$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() );
</syntaxhighlight>

<translate>
=== Feature support in JavaScript === <!--T:106-->
</translate>
{{warning|1=<translate><!--T:208--> Wikitext support in JS messages requires the <tvar name=1><code>mediawiki.jqueryMsg</code></tvar> module to be loaded, otherwise these features will be silently ignored.</translate>}}
<translate><!--T:209--> JavaScript messages only support a small subset of wikitext syntax. Supported features include:</translate>

* <translate><!--T:210--> Internal links (except [[<tvar name=1>Special:MyLanguage/pipe trick</tvar>|pipe trick]])</translate>
* <translate><!--T:211--> Explicit external links (no auto-numbered and free links)</translate>
* <translate><!--T:212--> The magic words <tvar name=1>SITENAME, PAGENAME, PAGENAMEE</tvar>; since MW 1.38: <tvar name=4>SERVERNAME</tvar>; since MW 1.43: <tvar name=5>CONTENTLANGUAGE</tvar></translate>
* <translate><!--T:213--> The parser functions <tvar name=1>PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst</tvar>; since MW 1.44: <tvar name="5">fullurl</tvar></translate>
* <translate><!--T:214--> HTML tags which are allowed in wikitext (HTML must be well-formed)</translate>
* <translate><!--T:215--> HTML entities <tvar name=1><code>&amp;#039;</code></tvar>, <tvar name=2><code>&amp;quot;</code></tvar>, <tvar name=3><code>&amp;lt;</code></tvar>, <tvar name=4><code>&amp;gt;</code></tvar>, <tvar name=5><code>&amp;amp;</code></tvar></translate>
* <translate><!--T:216--> The <tvar name=1>{{tag|nowiki|open}}</tvar> tag</translate>

<translate><!--T:217--> Notable wikitext syntax that is '''not''' supported:</translate>

* <translate><!--T:218--> Templates</translate>
* <translate><!--T:219--> [[<tvar name=1>metawiki:Special:MyLanguage/Help:Interwiki_linking#Non-local_interwikis</tvar>|Non-local interwiki links]]</translate>
* <translate><!--T:220--> All other parser functions and magic words</translate>
* <translate><!--T:221--> Modules (for example [[<tvar name=1>Special:MyLanguage/Module:String</tvar>|Module:String]])</translate>
* <translate><!--T:222--> All other XML-like tags (extension tags)</translate>
* <translate><!--T:223--> Bold and italic <tvar name=1><code><nowiki>'''</nowiki></code></tvar>, <tvar name=2><code><nowiki>''</nowiki></code></tvar> (use <tvar name=3>{{tag|b|open}}</tvar>, <tvar name=4>{{tag|i|open}}</tvar> instead)</translate>
* <translate><!--T:224--> Lists using <tvar name=1><code>*</code></tvar>, <tvar name=2><code>#</code></tvar> (use <tvar name=3>{{tag|ul|open}}</tvar> or <tvar name=4>{{tag|ol|open}}</tvar>, <tvar name=5>{{tag|li|open}}</tvar> instead)</translate>
* <translate><!--T:225--> Definition lists / indents using <tvar name=1><code>;</code></tvar>, <tvar name=2><code>:</code></tvar> (use <tvar name=3>{{tag|dl|open}}</tvar>, <tvar name=4>{{tag|dt|open}}</tvar>, <tvar name=5>{{tag|dd|open}}</tvar> instead)</translate>
* <translate><!--T:226--> Multiple paragraphs (use <tvar name=1>{{tag|p|open}}</tvar> instead)</translate>
* <translate><!--T:228--> Comments</translate> <syntaxhighlight lang=html inline><!-- --></syntaxhighlight>
* <translate><!--T:229--> Some types of nesting (e.g. <tvar name=1><syntaxhighlight lang="html" inline>{{PLURAL:$1|<strong>$1</strong>}}</syntaxhighlight></tvar>)</translate>

<translate>
<!--T:230-->
The [[<tvar name=1>translatewiki:Template:Doc-jqueryMsg</tvar>|doc-jqueryMsg template]] can be used to [[<tvar name=2>Special:MyLanguage/Help:System message#Message documentation</tvar>|document]] such messages, to let translators know which wikitext restrictions apply.
</translate>

=== mw.msg ===
<translate>
<!--T:231-->
The <tvar name=1><code>mw.msg()</code></tvar> function is commonly used as a shortcut for <tvar name=2><code>mw.message().text()</code></tvar>.

=== Exporting messages through ResourceLoader callbacks === <!--T:108-->
</translate>
<translate><!--T:232--> 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 [[<tvar name=1>ResourceLoader/Package files#Generated_content</tvar>|package files callback]] in your ResourceLoader module.</translate>
<translate><!--T:233--> When you do this, take care to use <tvar name=1>{{phpi|$context->msg()}}</tvar>, because using <tvar name=2><code>wfMessage()</code></tvar> will [[<tvar name=3>Special:MyLanguage/ResourceLoader/Package files#Common pitfall: using i18n messages in generated content callbacks</tvar>|cause errors]].</translate>

<translate>
== Using messages in Lua == <!--T:109-->
</translate>
<translate><!--T:234--> Modules written in Lua using <tvar name=1>{{ll|Extension:Scribunto|Scribunto}}</tvar> run similarly to templates and have access to MediaWiki messages.</translate>
<translate><!--T:235--> The MediaWiki Lua library includes the mw.message class for processing messages.</translate>
<translate><!--T:236--> Refer to the full [[<tvar name=1>Special:MyLanguage/Extension:Scribunto/Lua reference manual#Message library</tvar>|Lua message library]] documentation for the full API.</translate>
<translate><!--T:237--> Here is a simple example:</translate>

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

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- <translate nowrap><!--T:323--> This ensures number localization</translate>
	-- <translate nowrap><!--T:324--> Show the message in the language of the wiki. <tvar name=1>frame:preprocess</tvar> expands the <tvar name=2>{{plural}}</tvar> clause.</translate>
	return frame:preprocess( nmembersMsg:plain() )
end

return p
</syntaxhighlight>

<translate>
== Using messages in Vue.js == <!--T:339-->
</translate>
{{See also|Vue.js#Internationalization}}

<translate>
== Notes about gender, grammar, plural == <!--T:110-->
</translate>
: <translate><!--T:238--> See also [[<tvar name=1>#Switches in messages…</tvar>|#Switches in messages…]]; the syntax itself is documented at [[<tvar name=2>Special:MyLanguage/Help:Magic words#Localization</tvar>|Help:Magic words#Localization]] and related.</translate>

<translate><!--T:239--> In general, <tvar name=1>GENDER</tvar>, <tvar name=2>GRAMMAR</tvar> and <tvar name=3>PLURAL</tvar> magic words work identically in both PHP and JavaScript sides.</translate>

# <translate><!--T:240--> You must use <tvar name=1><code>text</code></tvar>, <tvar name=2><code>escaped</code></tvar>, <tvar name=3><code>parse</code></tvar> or <tvar name=4><code>parseAsBlock</code></tvar> [[<tvar name=5>#Output modes and escaping</tvar>|output formats]] for them to work.</translate>
#* <translate><!--T:241--> In PHP, you can use wfMessage or <tvar name=1><code>[[#Additional methods of printing messages|$this->msg]]</code></tvar>.</translate>
#* <translate><!--T:242--> In JavaScript, make sure your resource loader module depends on <tvar name=1><code>jqueryMsg</code></tvar> (see [[<tvar name=2>#Using messages in JavaScript</tvar>|#Using messages in JavaScript]]).</translate>
# <translate><!--T:243--> You need to pass the relevant parameter as normal parameter to the message.</translate>
#* <translate><!--T:244--> The parameter is the number for <tvar name=1>PLURAL</tvar>; the plain text or wikitext-escaped username for <tvar name=2>GENDER</tvar> in PHP; the gender from preferences or a user object for <tvar name=3>GENDER</tvar> in JavaScript ([[<tvar name=4>#GENDER in JavaScript</tvar>|see below]]).</translate>
#* <translate><!--T:245--> For enabling plural and correct number localization in PHP, you need to use <tvar name=1><code>numParams</code></tvar> for the number, see also [[<tvar name=2>#Chaining</tvar>|#Chaining]].</translate>
#* <translate><!--T:246--> For enabling plural and correct number localization in JavaScript, you need to use <tvar name=1><code>mw.language.convertNumber</code></tvar> for the number</translate>

<translate>
=== PLURAL syntax example === <!--T:111-->
</translate>
<syntaxhighlight lang="PHP">
# <translate nowrap><!--T:325--> Simple plural</translate>
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'
</syntaxhighlight>

{{anchor|JavaScript examples}}
<translate>
=== GENDER in JavaScript === <!--T:112-->
</translate>
{{note|1=<translate><!--T:247--> This needs explicit <tvar name=1><code>jqueryMsg</code></tvar>, see [[<tvar name=2>#Using messages in JavaScript</tvar>|#Using messages in JavaScript]].</translate>}}

<translate><!--T:248--> If you have a message, say, <tvar name=1><code><nowiki>"message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article"</nowiki></code></tvar>, in JavaScript, you can use it as given below:</translate>

<syntaxhighlight lang=javascript>
mw.message( 'message-key-gender-foo', 'male' ).text(); // <translate nowrap><!--T:326--> returns <tvar name=1>'he created an article'</tvar></translate>
mw.message( 'message-key-gender-foo', 'female' ).text(); // <translate nowrap><!--T:327--> returns <tvar name=1>'she created an article'</tvar></translate>
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // <translate nowrap><!--T:328--> returns <tvar name=1>'they created an article'</tvar></translate>
</syntaxhighlight>

<translate><!--T:249--> Instead of passing the gender directly, we can pass any "User-like" object with a gender option.</translate>
<translate><!--T:250--> For example, the current user object <tvar name=1><code>mw.user</code></tvar>.</translate>

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

<translate><!--T:251--> If the gender passed is invalid or unknown, the gender neutral form will be used as defined for each language.</translate>
<translate><!--T:252--> Pass <tvar name=1><code>'unknown'</code></tvar> if you intentionally want the neutral form.</translate>

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

<translate>
=== PLURAL in JavaScript === <!--T:113-->
</translate>
{{note|1=<translate><!--T:254--> This needs explicit <tvar name=1><code>jqueryMsg</code></tvar>, see [[<tvar name=2>#Using messages in JavaScript</tvar>|#Using messages in JavaScript]].</translate>}}

<translate><!--T:255--> If you have a message, say <tvar name=1><code><nowiki> 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 items}}' </nowiki></code></tvar> , in JavaScript, you can use it as given below:</translate>

<syntaxhighlight lang=javascript>
mw.message( 'message-key-plural-foo', count ).text();
// <translate nowrap><!--T:334--> returns <tvar name=1>'There is 1 item'</tvar> if count = 1</translate>
// <translate nowrap><!--T:335--> returns <tvar name=1>'There are 6 items'</tvar> if count = 6</translate>
</syntaxhighlight>

<translate>
== See also == <!--T:18-->
</translate>
* {{ll|API:Allmessages}}
* {{ll|Help:HTML_in_wikitext}}
* [[wmdoc:mediawiki-core/master/php/classMessage.html|<translate><!--T:297--> Message class documentation</translate>]]

<translate>
==Notes== <!--T:19-->
</translate>
<references/>
{{Parser functions nav}}

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