Manual:Messages API - MediaWiki

Manual:Messages API - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Bahasa Indonesia
Nederlands
català
magyar
polski
português
čeština
русский
українська
العربية
中文
i18n docs
Localisation
System message
Messages API
Language
translatewiki.net
Writing systems
Language Converter
Directionality
MediaWiki messages
can be used in the code through the Message class and its associated methods.
While the examples throughout this document make use of the global function
wfMessage()
, in most cases it is best not to use this global function. Instead, you should use an object that provides a
RequestContext
, and call
$context
->
msg
()
on it. In many classes, you can use
$this
->
msg
()
Message parameters
Some messages take parameters.
They are represented by
$1
$2
$3
, … in the (static) message texts, and replaced at run time.
Typical parameter values are numbers (the "3" in "Delete 3 versions?"), or user names (the "Bob" in "Page last edited by Bob"), page names, links and so on, or sometimes other messages.
They can be of arbitrary complexity.
The list of parameters defined for each specific message is placed in special file "qqq.json" located in "languages/" folder of MediaWiki - read more in
Message documentation
It's preferable to use whole words with the PLURAL, GENDER, and GRAMMAR magic words.
For example,
{{PLURAL:$1|subpage|subpages}}
is better than
sub{{PLURAL:$1|page|pages}}
It makes searching easier.
Referring to other messages
It's sometimes convenient to refer to sub-messages in a message, e.g. in phrases like "Use the X button" or "Visit the Y page", to ensure that the translations are consistent.
To do so, you may use the following syntax:
{{int:X}}
– to use the sub-message in interface language. This is often used when referring to form buttons or site navigation, e.g.
showpreview
{{MediaWiki:Y}}
– to use the sub-message in content language. This is used when the sub-message defines a translatable name of a local page, e.g.
mainpage
grouppage-sysop
policy-url
{{#Special:Z}}
– to use the name of a special page in content language.
If you need anything more complicated (e.g. the sub-message used depends on configuration), parse it in your code and pass the whole sub-message as a parameter.
Example:
Before saving, use the
{{
int
foo-test
}}
button to test the changes. Visit
[[{{
MediaWiki
foo-help
}}|
the help page
]]
to learn more.Customize this feature at
[[{{
#Special
Preferences
}}]]
Switches in messages…
Parameters values at times influence the exact wording, or grammatical variations in messages.
We don't resort to ugly constructs like "$1 (sub)page(s) of his/her userpage", because these are poor for users and we can do better.
Instead, we make switches that are parsed according to values that will be known at run time.
The static message text then supplies each of the possible choices in a list, preceded by the name of the switch, and a reference to the value that makes a difference.
This resembles the way
Parser functions
are called in MediaWiki.
Several types of switches are available.
These only work if you do full parsing, or
{{
-transformation, for the messages.
…on numbers via PLURAL
MediaWiki supports plurals, which makes for a nicer-looking product.
For example:
'undelete_short'
=>
'Undelete {{PLURAL:$1|one edit|$1 edits}}'
If there is an explicit plural form to be given for a specific number, it is possible with the following syntax:
'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'
Be aware of PLURAL use on
all
numbers
See also:
translatewiki:Plural
and
Help:Magic words#plural
When a number has to be inserted into a message text, be aware that some languages will have to use PLURAL on it even if always larger than 1.
The reason is that PLURAL in languages other than English can make very different and complex distinctions, comparable to English 1
st
, 2
nd
, 3
rd
, 4
th
, … 11
th
, 12
th
, 13
th
, … 21
st
, 22
nd
, 23
rd
, …
etc.
Do not try to supply three different messages for cases like "no items counted", "one item counted", "more items counted".
Rather, let one message take them all, and leave it to translators and PLURAL to properly treat any possible differences of presentation for them in their respective languages.
Always include the number as a parameter if possible.
Always add
{{PLURAL:}}
syntax to the source messages if possible, even if it makes no sense in English.
The syntax guides translators.
Fractional numbers are supported, but the plural rules may not be complete.
Pass the number of list items as parameters to messages talking about lists
Don't assume that there's only singular and plural.
Many languages have more than two forms, which depend on the actual number used and they have to use
grammar
varying with the number of list items when expressing what is listed in a list visible to readers.
Thus, whenever your code computes a list, include
count( $list )
as parameter to headlines, lead-ins, footers and other messages about the list, even if the count is not used in English.
There is a neutral way to talk about invisible lists, so you can have links to lists on extra pages without having to count items in advance.
…on user names via GENDER
'foobar-edit-review'
=>
'Please review {{GENDER:$1|his|her|their}} edits.'
If you refer to a user in a message, pass the user name as parameter to the message and add a mention in the message documentation that gender is supported.
If it is likely that GENDER will be used in translations for languages with gender inflections, add it explicitly in the English language source message.
If you directly address the currently logged-in user, leave the user name as parameter empty:
'foobar-logged-in-user'
=>
'You said {{GENDER:|you were male|you were female|nothing about your gender}}.'
MediaWiki version:
1.31
Gerrit change 398772
If you include the user name into the message (e.g.
$1 thanked you.
), consider passing it through
wfEscapeWikitext()
first, to ensure that characters like
or
are not interpreted.
Users have grammatical genders
See also:
translatewiki:Gender
and
Help:Magic words#gender
When a message talks about a user, or relates to a user, or addresses a user directly, the user name should be passed to the message as a parameter.
Thus languages having to, or wanting to, use proper gender dependent grammar, can do so.
This should be done even when the user name is not intended to appear in the message, such as in "inform the user on his/her talk page", which is better made "inform the user on {{GENDER:$1|his|her|their}} talk page" in English as well.
This does not mean that you are encouraged to "sexualise" messages' language: please use gender-neutral language whenever this can be done with clarity and precision.
…on use context inside sentences via GRAMMAR
Grammatical transformations for
agglutinative language
(Q171263)
is also available.
For example for Finnish, where it was an absolute necessity to make language files site-independent,
i.e.
to remove the Wikipedia references.
In Finnish, "about Wikipedia" becomes "Tietoja Wikipediasta" and "you can upload it to Wikipedia" becomes "Voit tallentaa tiedoston Wikipediaan".
Suffixes are added depending on how the word is used, plus minor modifications to the base.
There is a long list of exceptions, but since only a few words needed to be translated, such as the site name, we didn't need to include it.
MediaWiki has grammatical transformation functions for over 20 languages.
Some of these are just dictionaries for Wikimedia site names, but others have simple algorithms which will fail for all but the most common cases.
Even before MediaWiki had arbitrary grammatical transformation, it had a nominative/genitive distinction for month names.
This distinction is necessary for some languages if you wish to substitute month names into sentences.
Filtering special characters in parameters and messages
The other (much simpler) issue with parameter substitution is HTML escaping. Despite being much simpler, MediaWiki does a pretty poor job of it.
Using messages in PHP
Warning:
Make sure you always use one of the
output modes
mentioned below
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
()
);
Don't use the
formatnum
magic word in messages. Always format the numbers in code.
The following sections explain the code.
Parameters
Given a message like the following:
"msg"
"Values are $1, $2"
You pass parameters to messages that need them in several ways:
wfMessage
'msg'
'param1'
'param2'
->
plain
();
wfMessage
'msg'
->
params
'param1'
'param2'
->
plain
();
wfMessage
'msg'
'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'
->
plaintextParams
$userInput
->
plain
();
wfMessage
'msg'
->
numParams
$count
->
plain
();
wfMessage
'msg'
->
durationParams
$duration
->
plain
();
// MediaWiki 1.22+
wfMessage
'msg'
->
expiryParams
$expiry
->
plain
();
// MediaWiki 1.22+
wfMessage
'msg'
->
timeperiodParams
$period
->
plain
();
// MediaWiki 1.22+
wfMessage
'msg'
->
sizeParams
$size
->
plain
();
// MediaWiki 1.22+
wfMessage
'msg'
->
bitrateParams
$bitrate
->
plain
();
// MediaWiki 1.22+
params()
Normal message substitution parameter.
rawParams()
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.
plaintextParams()
Like
rawParams()
, 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.
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.
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.
wfMessage
'message-key'
->
inContentLanguage
();
wfMessage
'message-key'
->
inLanguage
$lang
);
Output modes and escaping
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
text()
– transforms the message text (see
MessageCache::transform()
) which transforms all
{{}}
including templates and parser functions like PLURAL and GENDER, 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()
Which output mode to use
Generally speaking, the most common modes you will use are
->parse()
and
->text()
You use ->parse() in most places where HTML markup is supported, and you use
->text()
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
Html
::
element
use
->text()
. You may also consider using
Html
::
rawElement
()
instead and using the
->parse()
mode.
If you are putting in text (third argument) of
Html
::
rawElement
()
, you should generally use
->parse()
If you are putting into the attributes (second argument) of
Html
::
rawElement
()
or
Html
::
element
()
, use
->parse()
If you are manually constructing HTML attributes, you should use
->escaped()
. However you should never manually construct HTML attributes
For
$out
->
addWikiText
()
where
$out
is an OutputPage object use
->text()
or
->plain()
. However consider if you would rather use
$out
->
addWikiMsg
instead.
For $out->addHTML() use
->parse()
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:
wfMessage
'key'
->
params
'apple'
->
numParams
$numOfApples
->
setContext
$context
->
inContentLanguage
()
->
parse
()
Additional methods of printing messages
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
'