Manual:Messages API

The current localisation system was introduced in MediaWiki 1.17, and replaced the now deprecated  functions.

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

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

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

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.