Manual:Messages API

Jump to: navigation, search
i18n docs LocalisationLocalisation · System messageHelp:System message · Messages APIManual:Messages API · LanguageManual:Language · · Writing systemsWriting systems · DirectionalityDirectionality support

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#General use (for developers).

Using messages in PHP[edit]

Here is a simple example:

$out = Xml::submitButton( wfMessage( 'submit' )->text() );

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

$out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() );

The following sections explain the code.


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

wfMessage( 'msg', 'param1', 'param2' )->plain();
wfMessage( 'msg' )->params( 'param1', 'param2' )->plain();
wfMessage( 'msg', array( 'param1', 'param2' ) )->plain();

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:

wfMessage( 'msg' )->params( $username )->plain();
wfMessage( 'msg' )->rawParams( $link )->plain();

wfMessage( 'msg' )->numParams( $count )->plain();
wfMessage( 'msg' )->durationParams( $duration )->plain(); // since MW 1.22
wfMessage( 'msg' )->expiryParams( $expiry )->plain(); // since MW 1.22
wfMessage( 'msg' )->timeperiodParams( $period )->plain(); // since MW 1.22
wfMessage( 'msg' )->sizeParams( $size )->plain(); // since MW 1.22
wfMessage( 'msg' )->bitrateParams( $bitrate )->plain(); // since MW 1.22

The first one is a normal message substitution parameter. The second one substitutes the rawParams 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.

Each function from the second group formats the value in a specific way before the substitution. numParams must be used if the message uses {{PLURAL:}}. 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 formatDuration, formatExpiry, formatTimePeriod, formatSize and formatBitrate, and are just shorthands for calling them directly.


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.

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

Output modes and escaping[edit]

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

  • plain(): returns the message text as-is; only parameters are substituted[1]
  • text(): transforms the message text (MessageCache::transform() which transforms all '{{}}', e.g., plurals), but neither escapes nor sanitizes
  • escaped(): same as 'text', but also escapes it for use in HTML
  • parse(): parses the message text from wikitext to HTML and sanitizes (MessageCache::parse() which calls the Parser)
  • parseAsBlock(): 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 wfMessage() or $this->msg(), you should always specify an output type. text() is appropriate when you're outputting it through addWikiText().

Method chaining[edit]

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:

wfMessage( 'key' )
	->params( 'apple' )
	->numParams( $numOfApples )
	->setContext( $context )

Additional methods of printing messages[edit]

The general message function in MediaWiki is wfMessage. 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:

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

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 msg that automatically sets the current context (language, current page etc.). It is therefore recommended to use $this->msg() for those classes, like special pages. Here is a non-exhaustive list of such classes:[2]

  • CategoryViewer
  • HTMLForm
  • LogEventsList
  • DifferenceEngine
  • OutputPage
  • IndexPager
  • ImageHistoryList
  • ApiBase
  • ChangesList
  • Skin
Warning Warning: The QuickTemplate class and its subclasses (BaseTemplate, VectorTemplate, MonoBookTemplate, UserloginTemplate, UsercreateTemplate) have a method named msg which is different from the one from ContextSource. In these classes $this->msg() will simply output the escaped text of the message.

Examples of correct usage:

wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();

Examples of incorrect usage:

wfMessage( 'key', 345 )->parseInline(); # Number is not formatted correctly
$this->msg( 'key', 345 )->numParams( 234 )->plain() # Plural syntax is not converted in plain format

Using messages in JavaScript[edit]

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

Getting the messages to the client[edit]

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[edit]

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

$resourcePaths = array(
        'localBasePath' => __DIR__,
        'remoteExtPath' => 'Translate'
$wgResourceModules['ext.translate.groupselector'] = array(
        'styles' => 'resources/css/ext.translate.groupselector.css',
        'scripts' => 'resources/js/ext.translate.groupselector.js',
        'position' => 'top',
        'dependencies' => array(
        'messages' => array(
) + $resourcePaths;

Using an API query from JavaScript[edit]

You can use the following code:

MediaWiki version: 1.27
// When: The 'mediawiki.api.messages' module is loaded, and, the page is ready
$.when( mw.loader.using( [ 'mediawiki.api.messages', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Then: Load the messages that you need (if they are not yet loaded)
    .then( function() {
        return new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] );
    } )
    // Then: Do stuff with them
    .then( doStuff );

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

// When: The 'mediawiki.api.messages' module is loaded. no need to wait for the page to be ready.
$.when( mw.loader.using( [ 'mediawiki.api.messages' ] ) )
    // Then: get some messages in French (language code 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Then: Do stuff with them
    .then( doStuff );
// doStuff is a function that will receive as its first parameter an object that looks like so:
// { february: "février", january: "janvier", march: "mars" }

For older MediaWiki versions before 1.27, use the following:

/** @return instance of jQuery.Promise */
function loadMessages( messages ) {
	return new mw.Api().get( {
		action: 'query',
		meta: 'allmessages',
		ammessages: messages.join( '|' ),
		amlang: mw.config.get( 'wgUserLanguage' )
	} ).then( function ( data ) {
		$.each( data.query.allmessages, function ( i, message ) {
			if ( message.missing !== '' ) {
				mw.messages.set(, message['*'] );
		} );
	} );

loadMessages( [ 'january', 'february', 'march' ] ).then( doStuff );

Use of the messages[edit]

The messages defined in the above example will be available at client side and can be accessed by mw.messages( 'message-key-name' ). Some examples

$( '<a>' ).prop( 'href', '#' ).text( mw.message( 'translate-msggroupselector-projects' ).text() );

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

$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', count ).text() );

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 .append, escape manually .append( '<li>' + mw.message( 'example' ).escaped() + '</li>' );
  • If manually building an html string, always escape the message by creating a message object and calling .escaped() (don't use mw.message().text() or the mw.msg shortcut):
    '<foo>' + mw.message( 'example' ).escaped() + '</foo>';

There are some more or less used aliases like gM (legacy shortcut for mw.jqueryMsg.getMessageFunction()) but its use is deprecated in favour of mw.message( ... ).parse().

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 <message-key-foo>.

To use a message that is natively HTML and has no other logic or variables, such as MediaWiki:copyright, use:

mw.message( 'copyright' ).plain()

Raw html messages are highly discouraged.

Format options[edit]

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:

  • mw.message( 'foobar' ).plain() returns the message text as-is; only parameters are substituted.
  • mw.message( 'foobar' ).text() Transforms the message text (all supported {{}} blocks are replaced with transformed results). See #Feature support in JavaScript for details of what is supported. For example, certain keywords ({{int:}}, {{GENDER}}, {{SITENAME}} etc.) work, but tranclusion (e.g. {{MediaWiki:}}) and server-side Magic words such as {{NUMBEROFEDITS}} or {{ns:Project}} do not work,
  • mw.message( 'foobar' ).escaped() HTML escaped version of text.
  • mw.message( 'foobar' ).parse() Parses the message text from wikitext to HTML. This supports everything from text mode, as well as most links, and whitelisted HTML.

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

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

Feature support in JavaScript[edit]

  • MediaWiki 1.19 onwards, the messages for JavaScript can contain PLURAL and GENDER directives.
  • MediaWiki 1.20 onwards, the messages for JavaScript can contain GRAMMAR directive.
  • MediaWiki 1.21 (1.21wmf8) onwards, the messages for JavaScript can contain uses of the INT directive.
  • MediaWiki 1.21 (1.21wmf9) onwards, some FORMATNUM support is available, primarily localization for digits and decimal separators.
  • MediaWiki 1.21 (1.21wmf10) onwards, messages can also have both wikilinks and external links. However, features like the pipe trick are not supported.
  • MediaWiki 1.22 (1.22wmf2) onwards, parsed messages can have limited HTML. Currently <b> and <i> are supported.

The keywords are case insensitive, but uppercase is preferred.


The mw.msg() function is commonly used as a shortcut for mw.message().text().

Using messages in Lua[edit]

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:

local p = {}

function p.nmembers( frame )
	local nmembersMsg = 'nmembers' )
	nmembersMsg:numParams( 3 ) -- This ensures number localization
	-- Show the message in the language of the wiki. frame:preprocess expands the {{plural}} clause.
	return frame:preprocess( nmembersMsg:plain() )

return p

Notes about gender, grammar, plural[edit]

See also Localisation#Switches in messages…; the syntax itself is documented at Help:Magic words#Localization and related.

In general, GENDER, GRAMMAR and PLURAL magic words work identically in both PHP and JavaScript sides.

  1. You must use text, escaped, parse or parseAsBlock output formats for them to work.
  2. You need to pass the relevant parameter as normal parameter to the message.
    • The parameter is the number for PLURAL; the plain text username for GENDER in PHP; the gender from preferences or a user object for GENDER in JavaScript (see below).
    • For enabling plural and correct number localization in PHP, you need to use numParams for the number, see also #Chaining.
    • For enabling plural and correct number localization in JavaScript, you need to use mw.language.convertNumber for the number

PLURAL syntax example[edit]

# Simple plural
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'

GENDER in JavaScript[edit]

Note: This needs explicit jqueryMsg, see #Using messages in JavaScript.

If you have a message, say, 'message-key-gender-foo' => '{{GENDER:$1|he|she}} created an article' , in JavaScript, you can use it as given below:

mw.message( 'message-key-gender-foo', 'male' ).text(); // returns 'he created an article'
mw.message( 'message-key-gender-foo', 'female' ).text(); // returns 'she created an article'

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 example, the current user object.

var user = mw.user; // current user
mw.message( 'message-key-gender-foo', user ).text(); // The message returned will be based on the gender of the current user.

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

Finally, if you just want to use the gender of current user, you can leave the parameter out:

// the following line illustrates the message content, you can run this snippet on developer console
mw.messages.set( 'message-key-gender-foo', '{{GENDER:|male|female|unknown}}' );
mw.message( 'message-key-gender-foo' ).text(); // return value depends on your gender preference

PLURAL in JavaScript[edit]

Note: This needs explicit jqueryMsg, see #Using messages in JavaScript.

If you have a message, say 'message-key-plural-foo' => 'There {{PLURAL:$1|is|are}} $1 {{PLURAL:$1|item|items}}' , in JavaScript, you can use it as given below:

mw.message( 'message-key-plural-foo', count ).text();
// returns 'There is 1 item' if count = 1
// returns 'There are 6 items' if count = 6

Help with replacing deprecated wfMsg* functions[edit]

These functions were removed starting with MediaWiki 1.27 LTS.

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;[3]
  • where possible, avoid globals and use msg() (see above);
  • replace htmlspecialchars() with ->escaped() where appropriate.
Code change Description
Instead of:
wfMsg( 'key' );


wfMessage( 'key' )->text();
Instead of:
wfMsgExt( 'key', SOME_FORMAT, 'apple' );


wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();
The second parameter specifies the output mode, usually expressed as an array like array( 'escape' ) but sometimes just like 'escape': it needs to be replaced according to #Output modes and escaping, like ->escaped().
Instead of:
wfMsgExt( 'key', array( 'parse' ), 'apple' );


wfMessage( 'key', 'apple' )->parseAsBlock();
Use full parsing, and wrap the output in block-level HTML tags.
Instead of:
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.
Instead of:
wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' );


wfMessage( 'key', 'apple', 'pear' )->text();
Places where HTML cannot be used. {{-transformation is done.
Instead of
wfMsgHtml( 'key', 'apple' );


wfMessage( 'key' )->rawParams( 'apple' )->escaped();
wfMsgHtml does not escape parameters: to get the same result you need to use rawParams; check that the parameter really is safe for html output. If the message is then output as HTML, you must use escaped() for security: it will escape the parameters too and that's not always wanted, although it doesn't matter e.g. when the parameter is a number.
Instead of:
wfMsgForContent( 'key' );


wfMessage( 'key' )->inContentLanguage()->text();
Get a message in the wiki's content language ($wgLanguageCode).
Instead of:
wfMsgForContentNoTrans( 'key' );


wfMessage( 'key' )->inContentLanguage()->plain();
Get a message in the wiki's content language ($wgLanguageCode) but don't transform the message.
Instead of:
wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) );


wfMessage( 'key' )->inContentLanguage()->isBlank();
Checks if the 'key' message in the wiki's content language is empty. Often, isDisabled() is a more appropriate check and should be used instead.
Instead of:
wfMsgReal( $error['message'], $error['params'] );


There is no simple replacement, depends on parameters. Should never have been used in the first place.
Instead of:


There is no simple replacement, depends on parameters. Should never have been used in the first place.

See also[edit]


  1. 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.
  2. More in general, use $this->msg() in non-static functions of IContextSource objects.
  3. For instance Xml::tags() doesn't escape.