Handleiding:Messages API

MediaWiki berichten kunnen in de code worden gebruikt via de class Message en de bijbehorende methods.

Parameters

Sommige berichten hebben parameters. Ze worden weergegeven door $1, $2, $3, ... in de (statische) berichtteksten en worden vervangen op het tijdstip van het uitvoeren. Typische parameters zijn getallen (de "3" in "Verwijder 3 versies?"), of gebruikersnamen (de "Bob" in "Pagina laatst bewerkt door Bob"), paginanamen, links en zo verder, of soms andere berichten. Ze kunnen van willekeurige complexiteit zijn.

De lijst met parameters die voor elk specifiek bericht zijn gedefinieerd, wordt in het speciale bestand "qqq.json" geplaatst in de map "languages/" van MediaWiki - lees meer in Bericht documentatie.

Het verdient de voorkeur om hele woorden te gebruiken met de magische woorden PLURAL, GENDER en GRAMMAR. (MEERVOUD, GESLACHT en GRAMMATICA) Voorbeeld: {{PLURAL:$1|subpagina|subpagina's}} is beter dan sub{{PLURAL:$1|pagina|pagina's}}. Het maakt het zoeken gemakkelijker.

Aan andere berichten refereren

Het is soms handig om in een bericht naar subberichten te verwijzen, bijvoorbeeld in zinnen als "Gebruik de knop X" of "Bezoek de pagina Y", om ervoor te zorgen dat de vertalingen consistent zijn. Hiervoor kunt u de volgende syntaxis gebruiken:

• {{int:X}} - om het subbericht in de interface taal te gebruiken. Dit wordt vaak gebruikt bij het verwijzen naar formulierknoppen of sitenavigatie, bijvoorbeeld showpreview.
• {{MediaWiki:Y}} - om het subbericht in de content taal te gebruiken. Dit wordt gebruikt wanneer het subbericht een vertaalbare naam van een lokale pagina definieert, bijvoorbeeld mainpage, grouppage-sysop, policy-url.
• {{#Special:Z}} - de naam van een speciale pagina in de content taal te gebruiken.

Als u iets ingewikkelders nodig heeft (bijvoorbeeld het subbericht dat wordt gebruikt, is afhankelijk van de configuratie), analyseer het in uw code en geef het hele subbericht als een parameter door.

Voorbeeld:

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 berichten…

Parameterwaarden beïnvloeden soms de exacte formulering of zorgen voor een grammaticaal verschil in berichten. We doen geen beroep op lelijke constructies zoals "$1 (sub)page(s) of his/her userpage", omdat deze slecht zijn voor gebruikers en we het beter kunnen doen. In plaats daarvan maken we switches die worden geanalyseerd volgens waarden die bekend zullen zijn op het tijdstip van het nodig hebben op een pagina van het bericht. De statische tekst van een bericht geeft vervolgens elk van de mogelijke keuzes in een lijst, voorafgegaan door de naam van de switch, en een verwijzing naar de waarde die een verschil maakt. Dit lijkt op de manier waarop Parserfuncties in MediaWiki wordt aangeroepen. Er zijn verschillende soorten switches beschikbaar. Deze werken alleen als u de berichten volledig analyseert, of een transformatie {{ voor de berichten.

…op aantallen via PLURAL

MediaWiki ondersteunt meervouden, waardoor het product er mooier uitziet. Bijvoorbeeld:

'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}',

Als er een expliciete meervoudsvorm voor een bepaald aantal is, is het mogelijk met de volgende syntaxis:

'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'

Let op het gebruik van PLURAL bij het getal alle

Zie ook: translatewiki:Plural

Wanneer een nummer in een berichttekst moet worden ingevoegd, houd er dan rekening mee dat sommige talen PLURAL moeten gebruiken, zelfs als het altijd groter is dan 1. De reden is dat PLURAL (meervoud) in andere talen dan het Engels heel verschillende en complexe onderscheidingen kan maken, vergelijkbaar met het Engels 1^st, 2^nd, 3^rd, 4^th, … 11^th, 12^th, 13^th, … 21^st, 22^nd, 23^rd, …

Probeer niet drie verschillende berichten te geven voor gevallen als "geen items geteld", "één item geteld", "meer items geteld". Laat ze liever allemaal maken met één bericht, en laat het aan de vertalers en PLURAL over om eventuele verschillen in presentatie voor hen in hun respectievelijke talen goed te behandelen.

Als het mogelijk is, moet het nummer altijd als parameter worden meegegeven. Voeg indien mogelijk altijd syntaxis {{PLURAL:}} toe aan de bronberichten, zelfs als het in het Engels geen zin heeft. De syntaxis is duidelijk voor de vertalers.

Decimalen worden ondersteund, maar de meervoud regels zijn mogelijk niet volledig.

Geef het aantal lijstitems als parameters door aan berichten die over lijsten gaan

Veronderstel niet dat er alleen enkelvoud en meervoud is. Veel talen hebben meer dan twee vormen, die afhankelijk zijn van het werkelijke aantal dat wordt gebruikt en ze moeten grammatica gebruiken, variërend van het aantal lijstitems bij het uitdrukken van wat er in een lijst staat die zichtbaar is voor lezers. Als uw code een lijst berekent, moet u count( $list ) dus als parameter voor koppen, inleidingen, voetregels en andere berichten over de lijst vermelden, zelfs als het aantal in het Engels niet wordt gebruikt. Er is een neutrale manier om over onzichtbare lijsten te praten, zodat u links naar lijsten op extra pagina's kunt hebben zonder vooraf items te hoeven tellen.

…op gebruikersnamen via GENDER

'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.'

Als u in een bericht naar een gebruiker verwijst, geeft u de gebruikersnaam als parameter door aan het bericht en voegt u een vermelding toe in de berichtdocumentatie dat het geslacht wordt ondersteund. Als het waarschijnlijk is dat GENDER zal worden gebruikt in vertalingen voor talen met onderscheid i.v.m. geslacht, voeg het expliciet toe in het bronmaatschap in de Engelse taal.

Als u de nu ingelogde gebruiker direct aanspreekt, laat dan de parameter met de gebruikersnaam leeg:

'foobar-logged-in-user' => 'You said {{GENDER:|you were male|you were female|nothing about your gender}}.'

MediaWiki-versie:

≥ 1.31 Gerrit change 398772

Als u de gebruikersnaam in het bericht (bijvoorbeeld "$1 bedankte u.") opneemt, overweeg dan eerst om het door wfEscapeWikitext() te laten gaan, om ervoor te zorgen dat tekens als * of ; niet worden geïnterpreteerd.

Gebruikers hebben grammaticale verschillen per sekse

Zie ook: translatewiki:Gender

Wanneer een bericht over een gebruiker spreekt, of zich met een gebruiker verbindt, of een gebruiker rechtstreeks aanspreekt, moet de gebruikersnaam als parameter aan het bericht worden doorgegeven. Daarom kunnen talen die een afhankelijk van het geslacht afhankelijke grammatica moeten gebruiken, dat doen. Dit moet zelfs worden gedaan als de gebruikersnaam niet bedoeld is om in het bericht te verschijnen, zoals in "informeer de gebruiker op zijn/haar overlegpagina", wat beter kan worden gemaakt "informeer de gebruiker op {{GENDER:$1|zijn|haar|diens}} overlegpagina".

Dit betekent niet dat u wordt aangemoedigd om de taal van de boodschappen te "seksualiseren": gebruik altijd een genderneutrale taal wanneer dit met duidelijkheid en precisie kan worden gedaan.

…op gebruik context binnen zinnen via GRAMMAR

Er zijn ook grammaticale transformaties voor agglutinerende taal (Q171263) beschikbaar. Bijvoorbeeld voor het Fins, waar het een absolute noodzaak was om taalbestanden site-onafhankelijk te maken, d.w.z. om de Wikipedia-verwijzingen te verwijderen. In het Fins wordt "about Wikipedia" "Tietoja Wikipediasta" en "you can upload it to Wikipedia" wordt "Voit tallentaa tiedoston Wikipediaan". Achtervoegsels worden toegevoegd afhankelijk van hoe het woord wordt gebruikt, plus kleine wijzigingen in de basisvorm. Er is een lange lijst met uitzonderingen, maar omdat er maar een paar woorden nodig waren om te worden vertaald, zoals de naam van de site, hoefden we het niet op te nemen.

MediaWiki heeft grammaticale transformatietechnologie voor meer dan 20 talen. Sommige van deze zijn gewoon woordenboeken voor de naam van Wikimedia-sites, maar anderen hebben eenvoudige algoritmen die voor veel, behalve de meest voorkomende gevallen, zullen falen.

Zelfs voordat MediaWiki een willekeurige grammaticale transformatie had, had het een nominatief/genitief onderscheid voor maandnamen. Dit onderscheid is voor sommige talen noodzakelijk als u de maandnamen in zinnen wilt vervangen.

Filteren speciale karakters in parameters en berichten

Het andere (veel eenvoudiger) probleem met parametersubstitutie is HTML-escapen. MediaWiki voert deze taak heel erg matig uit.

Berichten in PHP gebruiken

Waarschuwing:

Zorg ervoor dat u altijd een van de onderstaande uitvoermodi gebruikt

Een eenvoudig voorbeeld:

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

wfMessage() is een globale functie die als een wrapper voor de class Message fungeert en een object Message creëert. Dit voorbeeld roept vervolgens de methode Message text() aan die de tekst van het 'submit' bericht in de huidige taal haalt, bepaalde taaltransformaties (zoals geslacht en meervoud) uitvoert en de niet geëscapte berichttekst teruggeeft.

Hier is een complexer voorbeeld met een bericht met als invoer een aantal en dat een taalgebonden meervoud ondersteunt:

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

De volgende secties verklaren de code.

Parameters

Met een bericht als volgt:

{
    "msg": "Values are $1, $2"
}

U geeft parameters door aan berichten die ze nodig hebben op verschillende manieren:

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

De eerste benadering is het meest gebruikelijk, gebruik de tweede benadering bij het mengen van verschillende soorten parameters, en u kunt de derde gebruiken om berichtobjecten dynamisch te construeren op basis van andere gegevens. Er zijn verschillende soorten 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()

Normale parameter die een deel in een bericht vervangt.

rawParams()

Vervangt de parameter nadat het bericht anders is verwerkt; dit betekent dat deze parameters niet beschikbaar zijn voor parserfuncties, noch worden ze aangepast voor escapen als een dergelijk uitvoerformaat wordt gebruikt (zie hieronder). Zorg ervoor dat u zelf zorgt voor het escapen.

plaintextParams()

Als rawParams(), maar doet wel escapen. Het is handig wanneer u gebruikersinvoer doorgeeft die mogelijk wikitext bevat die niet moet worden verwerkt.

Elke functie uit de tweede groep formatteert de waarde op een specifieke manier vóór de vervanging. numParams() moet worden gebruikt als het bericht {{PLURAL:}} gebruikt. In sommige gevallen wilt u het misschien niet gebruiken, ook al heeft u een getal, bijvoorbeeld een ID van een revisie. De andere functies komen overeen met de taalfuncties formatDuration, formatExpiry, formatTimePeriod, formatSize en formatBitrate, en zijn slechts afkortingen om ze rechtstreeks aan te roepen.

Taal

Om de taal waarin u het bericht wilt overschrijven, is er één methode en een snelkoppeling voor de gebruikelijke wiki-taal van de inhoud. In het laatste geval kunt u een taalcode of een taalobject gebruiken. De gebruikelijke fallback ketens voor de taal gelden, dus het bericht dat u ontvangt kan in een andere taal dan de gevraagde zijn, indien er geen vertaling bestaat.

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

Uitvoermodi en escapen

De class Message en dus het object dat wordt teruggegeven door wfMessage() heeft vijf uitvoermodi:

• plain() - retourneert de berichttekst zoals deze is; alleen parameters worden gesubstitueerd
• text() - zet de berichttekst (zie MessageCache::transform()) om die alle {{}} transformeert, inclusief sjablonen en parserfuncties zoals PLURAL en GENDER, maar zorgt niet voor het escapen of opruimen van de tekst
• escaped() - is hetzelfde als 'text', maar zorgt ook voor het escapen voor het gebruik in HTML
• parse() - verwerkt de berichttekst van wikitext naar HTML en zorgt voor het 'opruimen' (MessageCache::parse() die de parser aanroept)
• parseAsBlock() - de uitvoer wordt ingepakt in een HTML-element op blokniveau, indien niet al, vergelijkbaar met OutputPage::addWikiMsg

Onthoud dat Html:: functies alles escapen wat erin wordt ingevoerd, dus gebruik daarbij het formaat text() om het dubbel escapen te voorkomen. Het meest voorkomende uitvoerformaat is dus text(). Zorg er ook voor dat u parse() of parseAsBlock() gebruikt als het bericht wikitext bevat, anders wordt de wikitext gewoon geescaped en als gewone tekst uitgevoerd.

Bij het gebruik van wfMessage() of $this->msg(), moet u altijd een uitvoertype vermelden. text() is geschikt als u het uitvoert via addWikiText().

Welke uitvoer mode te gebruiken

Over het algemeen zijn de meest voorkomende modi die u gebruikt ->parse() en ->text(). U gebruikt ->parse() op de meeste plaatsen waar html-markering wordt ondersteund, en u gebruikt ->text() op plaatsen waar de inhoud wordt html geescaped of html-markering niet wordt ondersteund.

Een aantal gewone gevallen:

• Als u het bericht in het tekstdeel (derde argument) van Html::element zet, gebruik dan ->text(). U kunt ook overwegen in plaats daarvan Html::rawElement() te gebruiken en de modus ->parse() te gebruiken.
• 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()

Methodes ketenen

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

Aanvullende methoden voor het afdrukken van berichten

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>', [ '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:

• CategoryViewer
• HTMLForm
• LogEventsList
• DifferenceEngine
• OutputPage
• IndexPager
• ImageHistoryList
• ApiBase
• ChangesList
• Skin

Waarschuwing:

De class QuickTemplate en zijn subclasses (BaseTemplate) hebben een methode genaamd msg die verschilt van die van ContextSource. In deze classes zal $this->msg() eenvoudig het geescapte tekstbericht teruggeven.

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

Berichten in JavaScript gebruiken

Zie ook: ResourceLoader/Core modules#mediaWiki.message

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 (most common) or an API query from JavaScript (rare).

Using a ResourceLoader module

Zie ook: Manual:$wgResourceModules

This is the most common method of delivering messages. U moet dit gebruiken, tenzij u een goede reden heeft om dit niet te doen.

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.

If you plan to use the mw.message(…).parse() to generate HTML from wikitext in interface messages, then it is important to load the mediawiki.jqueryMsg module.

Example (extension.json):

{
	"ResourceModules": {
		"ext.abuseFilter.edit": {
			"scripts": "ext.abuseFilter.edit.js",
			"messages": [
				"abusefilter-edit-syntaxok",
				"abusefilter-edit-syntaxerr",
				"abusefilter-http-error",
				"abusefilter-edit-throttle-placeholder",
				"abusefilter-edit-tag-placeholder",
				"abusefilter-edit-warn-leave",
				"unknown-error",
				"jan",
				"feb",
				"mar"
			],
			"dependencies": [
				"mediawiki.util",
				"mediawiki.api",
				"mediawiki.confirmCloseWindow",
				"jquery.textSelection",
				"jquery.spinner",
				"oojs-ui-core",
				"oojs-ui-widgets"
			]
		}
	}
}

Using an API query from JavaScript

Dit is geen gebruikelijke manier om berichten te laden. U moet dit alleen gebruiken als er een goede reden is waarom u de module ResourceLoader hierboven niet kunt gebruiken.

You can use the following code:

MediaWiki-versie:

≥ 1.27

// Wanneer: De module 'mediawiki.api' is geladen en de pagina is klaar
$.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Vervolgens: Laad de berichten die u nodig heeft (als ze nog niet geladen zijn)
    .then( function() {
        return new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] );
    } )
    // Dan: Do er wat mee
    .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' module is loaded. No need to wait for the page to be ready.
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Then: get some messages in French (language code 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Dan: Do er wat mee
    .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" }

Use of the messages

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

For example:

$( '<div>' ).text( mw.message( 'translate-msggroupselector-projects' ).text() );

Note how we use jQuery text method to escape our output properly when using mw.message text format.

If your message contains wikitext formatting, you can instead use the following:

$( '<div>' ).append( mw.message( 'translate-msggroupselector-projects' ).parseDom() );

Here we use jQuery append method to insert the DOM nodes returned by mw.message parseDom format.

In older code you might also encounter the following: (parseDom was not available until MediaWiki 1.27)

$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).escaped() );
$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).parse() );

There are other correct combinations, but whenever possible, stick to the patterns above to avoid XSS vulnerabilities and make your code easier to understand for others.

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( 'hello-user', username ).text() );

In de bovenstaande voorbeelden moet worden opgemerkt dat het bericht in een i18n-bestand moet worden gedefinieerd. If the message key is not found in any i18n file, the result will be the message key in curved angle brackets U+29FC/U+29FD (part of mathematical symbols), like '⧼message-key-foo⧽'. In older versions of MediaWiki, the message key was returned in ASCII angle brackets, like '<message-key-foo>', and this could generate invalid or fake HTML elements. In the case where the message key does not exists, the .exists() method of the returned message object will also return false instead of true.

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:

mw.message( 'foobar' ).plain()

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:

• 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:}} (but only without parameters), {{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 allow listed HTML.
• mw.message( 'foobar' ).parseDom() Like parse(), but returns a jQuery collection instead of a HTML string.

Waarschuwing:

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

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 mw.message(). 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 plaintextParams().

DOM/jQuery parameters can be used to achieve the equivalent of rawParams().

There is no support for other parameter formats. Instead of numParams(), you must format numbers before passing them as parameters, using mw.language.convertNumber().

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

Feature support in JavaScript

Waarschuwing:

Wikitext support in JS messages requires the mediawiki.jqueryMsg module to be loaded, otherwise these features will be silently ignored.

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)
• The magic words SITENAME, PAGENAME, PAGENAMEE, (in MW 1.38+) SERVERNAME, (in MW 1.43+) CONTENTLANGUAGE
• The 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 ‎<nowiki> tag

Notable wikitext syntax that is not supported:

• Templates
• Non-local interwiki links
• All other parser functions and magic words
• Modules (for example Module:String)
• All other XML-like tags (extension tags)
• Bold and italic ''', '' (use ‎<b>, ‎<i> instead)
• Lists using *, # (use ‎<ul> or ‎<ol>, ‎<li> instead)
• Definition lists / indents using ;, : (use ‎<dl>, ‎<dt>, ‎<dd> instead)
• Multiple paragraphs (use ‎<p> instead)
• Self-closing HTML tags
• Comments <!-- -->
• Some types of nesting (e.g. {{PLURAL:$1|<strong>$1</strong>}})

The doc-jqueryMsg template can be used to document such messages, to let translators know which wikitext restrictions apply.

mw.msg

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

Exporting messages through ResourceLoader callbacks

If you need to process a message on the server and send the result to the client (e.g. because you need to parse the message using parsing features that aren't supported in JS), you can do that with a package files callback in your ResourceLoader module. When you do this, take care to use $context->msg(), because using wfMessage() will cause errors.

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:

local p = {}

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( '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() )
end

return p

Notes about gender, grammar, plural

See also #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.
   • In PHP, you can use wfMessage or $this->msg.
   • In JavaScript, make sure your resource loader module depends on jqueryMsg (see #Using messages in JavaScript).
2. You need to pass the relevant parameter as normal parameter to the message.
   • 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).
   • 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

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

GENDER in JavaScript

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

If you have a message, say, "message-key-gender-foo": "{{GENDER:$1|he|she|they}} 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'
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // returns 'they created an article'

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

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 is invalid or unknown, the gender neutral form will be used as defined for each language. Pass 'unknown' 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:

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

PLURAL in JavaScript

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

If you have a message, say 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 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

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;
• where possible, avoid globals and use msg() (see above);
• replace htmlspecialchars() with ->escaped() where appropriate.

Code change	Description
Instead of: wfMsg( 'key' ); write: wfMessage( 'key' )->text();
Instead of: wfMsgExt( 'key', SOME_FORMAT, 'apple' ); write: 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' ); write: wfMessage( 'key', 'apple' )->parseAsBlock();	Use full parsing, and wrap the output in block-level HTML tags.
Instead of: wfMsgExt( 'key', array( 'parseinline' ), 'apple' ); write: 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' ); write: wfMessage( 'key', 'apple', 'pear' )->text();	Places where HTML cannot be used. {{-transformation is done.
Instead of wfMsgHtml( 'key', 'apple' ); write: 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' ); write: wfMessage( 'key' )->inContentLanguage()->text();	Get a message in the wiki's content language ($wgLanguageCode ).
Instead of: wfMsgForContentNoTrans( 'key' ); write: 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' ) ); write: 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'] ); write: ?	There is no simple replacement, depends on parameters. Should never have been used in the first place.
Instead of: wfMsgGetKey write: ?	There is no simple replacement, depends on parameters. Should never have been used in the first place.

Zie ook

• API:Allmessages
• Help:HTML_in_wikitext
• Message class documentation