Manual:Messages API

The current  localisation system was introduced in MediaWiki 1.17, and replaced the now deprecated   functions. In JavaScript, we use a ResourceLoader module, jqueryMsg.

Automatically generated documentation from trunk:
 * https://svn.wikimedia.org/doc/classMessage.html#_details

See also Localisation for general guidelines and in particular Localisation.

Using messages in PHP
The message system in MediaWiki is quite complex, a bit too complex. One of the reasons for this is that MediaWiki is a web application. Messages can go through all kinds of processing. The four three major ones covering almost all cases are:
 * 1) as-is, no processing at all
 * 2) light wiki-parsing, parser function references starting with  are replaced with their results
 * 3) full wiki-parsing

Case 1. is for processing, not really for user visible messages. Light wiki-parsing should always be combined with html-escaping.

Longer messages that are not used hundreds of times on a page can use:
 * OutputPage::addWikiMsg
 * OutputPage::wrapWikiMsg
 * wfMessage

wfMessage
Messages with light wiki-parsing can use  with. wfMessage should always be used if the message has parts that depend on linguistic information, like NaN undefineds.

Some messages have mixed escaping and parsing. Most commonly when using raw links in messages that should not be escaped. The preferred way is to use  with   for the affected parameters.

Remember that almost all Xml:: and Html:: functions escape everything fed into them, so avoid double-escaping and parsed text with those.

Basics
returns a  object that allows to manipulate the system messages. You can supply message parameters with. To use raw parameters that will be substituted after the rest of the message is parsed and/or escaped, use. You must take care yourself that those parameters are HTML-safe and don't introduce an XSS.

Language
By default, messages are displayed in the user language. In some cases, they need to be:
 * In the wiki content language
 * In any specific language, where $lang is a language code (string) or Language object.
 * In any specific language, where $lang is a language code (string) or Language object.

Format
It is recommended to specify the output format at the end of. It defaults to 'parse'.
 * returns the message text as-is; only parameters are substituted.
 * transforms the message text (MessageCache::transform which transforms all ' ')
 * same as 'text', but also escapes it (htmlspecialchars)
 * parses the message text from wikitext to HTML (MessageCache::parse which calls the Parser)
 * returns the parsed message text which is always surrounded by a block element, i.e. the message text will be added in a paragraph tag.

Call chaining
Most functions of this class return the current object, so you can conveniently make chained calls that do several operations with the object at once:

Other functions
OutputPage methods parse messages and add them directly to the output buffer. can be used when a message should not be added to the output buffer. removes enclosing HTML tags from the parsed result, usually, but can generate invalid code for example if there is no root tag in parsed result, for example. Usage examples:

Short list of functions to avoid:
 * OutputPage::parse and parseInline, addWikiText (if you know the message, use  or  )

Request context
The  class can use information about current user, his language and so on from RequestContext. It is therefore recommended to use  from classes that implement , such as special pages. It will automatically make interface messages aware of everything they need to be as much user-oriented as possible. Also it makes your code not dependent on a global function.

Suggestion for how to pass messages around
When you are building a new interface and need to pass messages from other parts of the code, consider using  objects for that. They are far more flexible than plain string message keys (no parameters!) or arrays of strings and message keys. Lots of old code is not yet accepting Message objects.

Using messages in JavaScript
It is important to note that loading the mediawiki.jqueryMsg module significantly changes the behavior of mw.message and mw.msg. Generally, you should load jqueryMsg if you want anything more complicated than substitution of dollar-sign variables.

mw.message and mw.msg

 * ''See also ResourceLoader/Default modules

To use the messages in client side, we need to use ResourceLoader to make sure that the messages are available at client side first. For this, in your ResourceLoader modules, define the messages to be exported to client side.

Example:

The messages defined in the above example,   will be available at client side and can be accessed by   (this is a shortcut equivalent to  ). See the example given below: We can also pass the dynamic parameters to the message (i.e. the values for $1, $2, etc.) as shown below.

In the above examples, note that the message should be defined in an i18n.php file. If the message key is not found in any i18n.php file, the result of mw.msg will be the message key in angle brackets - like .

When using localization messages, many messages (e.g. a label or title) should be treated as plain text. In such cases, you have two options:
 * Pass it explicitly as text:
 * To do this, instead of jQuery's, use  . jQuery will make sure to set the elements' inner text value instead of the raw html. This is the best option and is also fastest in performance because it avoids escaping all together because .text goes almost straight into the browser, removing the need for escaping.
 * Properly escape it to prevent potential HTML injections, as well as prevent malformed markup with special characters:
 * If using jQuery's, escape manually
 * If manually building an html string, escape manually by creating a message object and calling  (instead of the   shortcut ):

In some other cases, you will want to use the original HTML. This should generally be safe if there are no dollar-sign variables, since by default the MediaWiki namespace can only be edited by trusted users. You should review the HTML in question before using it, since if used improperly, this could allow unwanted HTML injection. To use a message that is natively HTML and has no other logic or variables, such as MediaWiki:stub-threshold, use:

Format options
If you don't specify the output format, mw.message just returns a Message object. To output the message itself, you should specify an output format. The options are:
 * returns the message text as-is; only parameters are substituted.
 * With jqueryMsg loaded, transforms the message text (all ' ' blocks are replaced with transformed results). Otherwise, same as 'plain'.
 * With jqueryMsg loaded, escaped version of 'text'. Otherwise, effectively escaped version of 'plain'.  Either way, escaping is equivalent to htmlspecialchars.
 * With jqueryMsg loaded, parses the message text from wikitext to HTML. However, only certain features are supported.  Otherwise, same as 'plain'.

You can also use, which defaults to using the   format. The  shortcut also defaults to using   and is equivalent to   or.

mediawiki.jqueryMsg
A more advanced message parser is available in a separate module, mediawiki.jqueryMsg. This is optional and extensions that require this feature should define an additional dependency  in the resourceloader module definition. It provides the below capabilities:

PLURAL and GENDER support in JavaScript
Mediawiki 1.19 onwards, the messages for JavaScript can contain PLURAL and GENDER directives.

The keywords GENDER, PLURAL are case insensitive.

See below for how to provide and use messages supporting PLURAL and GENDER.

GRAMMAR in JavaScript
MediaWiki 1.20 onwards, the messages for JavaScript can contain GRAMMAR directive.

The static grammar form rules can be defined in $wgGrammarForms global. The dynamic language specific grammar rules in PHP has been ported to JavaScript. Once the dependency  is added, mw.msg method can be used as usual to parse the messages with  where N is the name of the grammatical form needed and word is the word being operated on. More information about Grammar on translatewiki.net.

and links
From MediaWiki 1.21wmf8 onwards, the messages for JavaScript can contain uses of the int magic word.

They can also have both wikilinks and external links. However, features like the pipe trick are not supported.

Examples
Here are some examples and how-tos on how to use MediaWiki standard resources properly to follow localisation guidelines.

Add GENDER support

 * ''See also Bug 30443 – GENDER (tracking)

PHP

 * 1) Use wfMessage or $this->msg in classes that extend ContextSource, like special pages. Here is an incomplete list:
 * 2) * class CategoryViewer extends ContextSource
 * 3) * class HTMLForm extends ContextSource
 * 4) * class LogEventsList extends ContextSource
 * 5) * class DifferenceEngine extends ContextSource
 * 6) * class OutputPage extends ContextSource
 * 7) * class IndexPager extends ContextSource
 * 8) * class ImageHistoryList extends ContextSource
 * 9) * class ApiBase extends ContextSource
 * 10) * class ChangesList extends ContextSource
 * 11) * abstract class Skin extends ContextSource
 * 12) Pass a username in plain text
 * 13) Use either ,  ,   or  : see  above.

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

Instead of passing the gender directly, we can pass a User object - i.e. mw.User object with a gender attribute to mw.msg. For e.g., the current user object.

If the gender passed to mw.msg is invalid or unknown, gender neutral form will be used as defined for each language.

Add PLURAL support

 * See also Bug 38781 – Messages needing PLURAL support

How to make sure message supports plural:
 * 1) use correct functions,
 * 2) pass the number and
 * 3) use the correct output format.

PHP

 * 1) Use wfMessage or $this->msg in classes that extend ContextSource, like special pages. Here is an incomplete list:
 * 2) * class CategoryViewer extends ContextSource
 * 3) * class HTMLForm extends ContextSource
 * 4) * class LogEventsList extends ContextSource
 * 5) * class DifferenceEngine extends ContextSource
 * 6) * class OutputPage extends ContextSource
 * 7) * class IndexPager extends ContextSource
 * 8) * class ImageHistoryList extends ContextSource
 * 9) * class ApiBase extends ContextSource
 * 10) * class ChangesList extends ContextSource
 * 11) * abstract class Skin extends ContextSource
 * 12) Pass the number using   (remember the s; see also  )
 * 13) Use either ,  ,   or  : see  above.

Examples of correct usage: Examples of incorrect usage:

JavaScript
Make sure your resource loader module depends on.

Here is a real example:

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

Another example:

Always use  with. In other cases you need to escape with.

Rationale
Problems with the deprecated message system:
 * Many function with many parameters are confusing
 * The simple case is complicated to do
 * The simple way to do is wrong (wfMsg)
 * wfMsg replaces variables after {{-transform, does not parse nor escape
 * When fallbacks message is used, parsing in wrong language can lead to really broken results. Think about a language which has three plurals – English definition has only two, but it is parsed with the interface language. It used to be worse before all plural functions were made to use the last supplied value if there is too few given. This also affects other language dependent stuff like grammar.
 * replaceafter affects all parameters, where it is usually needed only for some of them
 * parsemag (or {{-transform, escape, parse, parseinline... hard to get it right

Suggested solution for all problems above expect parsing in a wrong language, since that problem is much deeper.

Old wfMsgExt

 * ''This section is outdated

wfMsgExt is a deprecated function within GlobalFunctions.php to retrieve the contents of a system message as listed in Special:Allmessages


 * function wfMsgExt( $key, $options ) : string.

returned string is value of the specified system message for the currently active language.

$key string representing a valid message-id

$options is a string containing one of the following options (or an array containing one or more of these strings):