Manual:Messages API

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

Automatically generated documentation from trunk:

• https://svn.wikimedia.org/doc/classMessage.html#_details

Basics

wfMessage( 'message-key' ) returns a Message object that allows to manipulate the system messages. You can supply message parameters with wfMessage( 'message-key', 'param1', $param2 ). To use raw parameters that will be substituted after the rest of the message is parsed and/or escaped, use wfMessage( 'message-key' )->rawParams( 'param1', $param2 ). 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

  wfMessage( 'message-key' )->inContentLanguage();

• In any specific language, where $lang is a language code (string) or Language object.

  wfMessage( 'message-key' )->inLanguage( $lang );

Format

It is recommended to specify the output format at the end of wfMessage( 'message-key' );. It defaults to 'parse'.

• wfMessage()->plain(); returns the message text as-is; only parameters are substituted.
• wfMessage()->text(); transforms the message text (MessageCache::transform() which transforms all '{{}}')
• wfMessage()->escaped(); same as 'text', but also escapes it (htmlspecialchars)
• wfMessage()->parse(); parses the message text from wikitext to HTML (MessageCache::parse() which calls the Parser)
• wfMessage()->parseAsBlock(); 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 (<p>Message text.</p>).

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:

wfMessage( 'key' )
        ->params( 'apple' )
        ->setContext( $context )
        ->inContentLanguage()
        ->parse()

Request context

The Message class can use information about current user, his language and so on from RequestContext. It is therefore recommended to use $this->msg() from classes that implement IContextSource, 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.

Comparison with the deprecated wfMsg* functions

Old way	Current way	Description
wfMsgExt( 'key', array( 'parseinline' ), 'apple' );	wfMessage( 'key', 'apple' )->parse();	Use full parsing. Parseinline is used because it is more useful when pre-building HTML. In normal use it is better to use OutputPage::(add|wrap)WikiMsg.
wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' );	wfMessage( 'key', 'apple', 'pear' )->text();	Places where HTML cannot be used. {{-transformation is done.
wfMsgHtml( 'key', 'apple' );	wfMessage( 'key' )->rawParams( 'apple' )->escaped();	Shortcut for escaping the message too, similar to wfMsgHTML, but parameters are not replaced after escaping by default.
wfMsgForContent( 'key' );	wfMessage( 'key' )->inContentLanguage()->text();	Get a message in the wiki's content language ($wgLanguageCode).
wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) );	wfMessage( 'key' )->inContentLanguage()->isBlank();	Checks if the 'key' message in the wiki's content language is empty.

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.