Manual:Messages API

MediaWiki messages can be used in the code through the Message class and its associated methods. For instructions on the messages themselves, and tips on how to add new messages, see Localisation and in particular Localisation.

Using messages in PHP
Here is a simple example:

is a global function which acts as a wrapper for the Message class, creating a Message object. This example then invokes Message method  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.

Here is a more complex example using a message that takes a count and supports linguistic plural handling: The following sections explain the code.

Parameters
You pass parameters to messages that need them in several ways:

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:


 * : Normal message substitution parameter.
 * : 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). Make sure you escape them properly yourself.
 * : Like, but does escaping. It is useful when you pass user input that may contain wikitext that should not be parsed.

Each function from the second group formats the value in a specific way before the substitution. must be used if the message uses. In some cases you might not want to use it even though you have a number, for example a revision id. The other functions correspond to Language functions,  ,  ,   and  , and are just shorthands for calling them directly.

Language
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. In the latter case you can use either a language code or a language object. 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.

Output modes and escaping
The Message class, and thus the object returned by wfMessage, has five output modes:


 * : returns the message text as-is; only parameters are substituted
 * : transforms the message text (MessageCache::transform which transforms all ' – ', e.g., plurals), but neither escapes nor sanitizes
 * : same as 'text', but also escapes it for use in HTML
 * : parses the message text from wikitext to HTML and sanitizes (MessageCache::parse which calls the Parser)
 * : the output is wrapped in a block level HTML element, if not already, similarly to OutputPage::addWikiMsg

Remember that Html:: functions escape everything fed into them, so use the text format with those to avoid double escaping. Hence the most common output format is text. 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.

When using  or , you should always specify an output type. is appropriate when you're outputting it through.

Which output mode to use
Generally speaking, the most common modes you will use are  and. You use ->parse in most places where html markup is supported, and you use  in places where the content is going to become html escaped or html markup is not supported.

Some common cases:
 * If you are putting the message in the text part (third argument) of  use  . You may also consider using   instead and using the   mode.
 * If you are putting in text (third argument) of, you should generally use.
 * If you are putting into the attributes (second argument) of  or , use
 * If you are manually constructing html attributes, you should use . However you should never manually construct html attributes
 * For  where   is an OutputPage object use   or  . However consider if you would rather use   instead.
 * For $out->addHTML use

Method chaining
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. This is called method chaining. Here is an example:

Additional methods of printing messages
The general message function in MediaWiki is. However, since in a message the value of magic words can depend on the context, there are various wrappers to this function, that automatically set the correct context.

OutputPage has a few methods that append directly to the generated output. The useful ones are:

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

Classes extending ContextSource have a method  that automatically sets the current context (language, current page etc.). It is therefore recommended to use  for those classes, like special pages. Here is a non-exhaustive list of such classes:
 * CategoryViewer
 * HTMLForm
 * LogEventsList
 * DifferenceEngine
 * OutputPage
 * IndexPager
 * ImageHistoryList
 * ApiBase
 * ChangesList
 * Skin

Examples of correct usage: Examples of incorrect usage:

Using messages in JavaScript

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

Getting the messages to the client
To use the messages, we need to make sure that the messages are available at client side first. This can be done using either a ResourceLoader module or an API query from JavaScript.

Using a ResourceLoader module
We are going to use ResourceLoader to make sure that the messages are available at the client side. For this, in your ResourceLoader modules, define the messages to be exported to the client side. It is important to note that loading the mediawiki.jqueryMsg module significantly changes the behavior of mw.message and mw.msg. Generally, you should always load jqueryMsg.

Abbreviated real example (PHP):

Using an API query from JavaScript
You can use the following code:

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

For older MediaWiki versions before 1.27, use the following:

Use of the messages
The messages defined in the above example will be available at client side and can be accessed by. Some examples

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

Note how we are using [jQuery].text to automatically escape our output properly. If this is not possible, here are few other examples:
 * If using jQuery's, escape manually
 * If manually building an html string, always escape the message by creating a message object and calling  (don't use   or the   shortcut ):

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

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

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

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

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

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

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

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

There is no support for other parameter formats. You can format numbers before passing them as parameters using.

Feature support in JavaScript
JavaScript messages only support a small subset of wikitext syntax. Supported features include:


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

Notable wikitext syntax that is not supported::


 * Templates
 * All other parser functions and magic words
 * All other XML-like tags (extension tags)
 * Bold and italic,   (use  ,   instead)
 * Lists using,   (use  / ,   instead)
 * Definition lists / indents using,   (use  ,  ,   instead)
 * Multiple paragraphs (use  instead)
 * Comments

mw.msg
The  function is commonly used as a shortcut for.

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

Notes about gender, grammar, plural

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

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

GENDER in JavaScript
Note: This needs explicit, see .

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

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

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

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

PLURAL in JavaScript
Note: This needs explicit, see .

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

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