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.
• Als u text (derde argument) van Html::rawElement() invoert, moet u over het algemeen ->parse() gebruiken.
• Als u de attributes (tweede argument) van Html::rawElement() of Html::element() invult, gebruik dan ->parse()
• Als u html-attributen handmatig bouwt, moet u ->escaped() gebruiken. Het handmatig html-attributen bouwen moet u eigenlijk niet doen.
• Voor $out->addWikiText() waar $out een object OutputPageis, gebruik ->text() of ->plain(). Denk er echter eens na of u niet beter $out->addWikiMsg kunt gebruiken.
• Voor $out->addHTML() gebruik ->parse()

Methodes ketenen

De meeste methoden van Messages geven het huidige object terug, zodat u gemakkelijk een na een andere aanroep kunt doen om op een object te werken voordat u uiteindelijk de tekst teruggeeft. Dit wordt method chaining genoemd. Een voorbeeld:

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

Aanvullende methoden voor het afdrukken van berichten

De algemene berichtenfunctie in MediaWiki is wfMessage. Omdat de waarde van magische woorden in een bericht echter afhankelijk is van de context, zijn er verschillende wrappers voor deze functie, die automatisch de juiste context instellen.

OutputPage heeft een paar methoden die direct worden toegevoegd aan de gegenereerde output. De nuttige zijn:

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

Beide bovenstaande ontleden de wikitext in de context van de huidige pagina voordat deze wordt toegevoegd aan het uitvoerbuffer.

Classes die ContextSource uitbreiden, hebben een methode msg die automatisch de huidige context instelt (taal, huidige pagina enz.). Het is daarom aan te raden om $this->msg() te gebruiken voor die classes, zoals de speciale pagina's. Een niet-uitputtende lijst van dergelijke 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.

Voorbeelden van correct gebruik:

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

Voorbeelden van verkeerd gebruik:

wfMessage( 'key', 345 )->parseInline(); # Het nummer is niet goed geformatteerd
$this->msg( 'key', 345 )->numParams( 234 )->plain() # De syntaxis van het meervoud is niet het gewone formaat omgezet

Berichten in JavaScript gebruiken

Zie ook: ResourceLoader/Core modules#mediaWiki.message

Deze pagina gaat alleen over MediaWiki core. Zie de specifieke documentatie voor de module jquery.i18n.

De berichten bij de client krijgen

Om de berichten te gebruiken, moeten we ervoor zorgen dat de berichten eerst beschikbaar zijn aan de client-zijde. Dit kan worden gedaan met behulp van een module ResourceLoader (meest gebruikelijk) of een API-query van JavaScript (zelden).

De module ResourceLoader gebruiken

Zie ook: Manual:$wgResourceModules

Dit is de meest voorkomende methode om berichten af te leveren. U moet dit gebruiken, tenzij u een goede reden heeft om dit niet te doen.

We gaan ResourceLoader gebruiken om ervoor te zorgen dat de berichten beschikbaar zijn aan de client-zijde. Hiervoor moet u in uw ResourceLoader-modules de berichten die naar de client-zijde moeten worden uitgevoerd, definiëren.

Als u van plan bent om de mw.message(…).parse() te gebruiken om HTML te genereren van wikitext in interface berichten, dan is het belangrijk om de module mediawiki.jqueryMsg te laden.

Voorbeeld (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"
			]
		}
	}
}

Een API-query van JavaScript gebruiken

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.

U kunt de volgende code gebruiken:

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

Als u de berichten in een andere taal dan de UserLanguage-taal wilt ontvangen, gebruik dan getMessages in plaats van loadMessagesIfMissing en geeft u de doeltaal op als het "amlang"-veld van de optionele tweede parameter, als volgt:

// Wanneer: De module 'mediawiki.api' wordt geladen. U hoeft niet te wachten tot de pagina klaar is.
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Dan: een paar berichten krijgen in French (taalcode 'fr')
    .then( function() {
        return new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' }  );
    } )
    // Dan: Do er wat mee
    .then( doStuff );
// doStuff is een functie die als eerste parameter een object krijgt dat eruit ziet als:
// { february: "février", january: "janvier", march: "mars" }

Berichten gebruiken

De berichten die in het bovenstaande voorbeeld zijn gedefinieerd, zijn beschikbaar aan de client-zijde en kunnen worden benaderd met mw.message( 'message-key-name' ).

Bijvoorbeeld:

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

Let op hoe we jQuery-methode text gebruiken om de output goed te escapen bij het gebruik van formaat mw.message text.

Als uw bericht opmaak van wikitext bevat, dient u het volgende gebruiken:

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

Hier gebruiken we jQuery-methode append om de DOM-nodes die worden teruggegeven door het formaat mw.message parseDom in te voeren.

In oudere code kunt u ook het volgende tegenkomen: (parseDom is pas beschikbaar vanaf MediaWiki 1.27)

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

Er zijn andere correcte combinaties, maar waar mogelijk, blijf bij de patronen hierboven om XSS-kwetsbaarheden te voorkomen en uw code voor anderen gemakkelijker leesbaar te houden.

We kunnen ook de dynamische parameters doorgeven aan het bericht (d.w.z. de waarden voor $1, $2, enz.) zoals hieronder gedaan wordt.

$( '<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. Als de berichtsleutel niet in een i18n-bestand wordt gevonden, zal het resultaat de berichtsleutel zijn in met aparte haakjes U+29FC/U+29FD (deel van wiskundige symbolen), zoals '⧼message-key-foo⧽'. In oudere versies van MediaWiki werd de berichtsleutel teruggegeven zoals '<message-key-foo>', en dit kon ongeldige of valse HTML-elementen genereren. In het geval dat de berichtsleutel niet bestaat, zal de methode .exists() van het teruggestuurd bericht object ook 'false' teruggeven in plaats van 'true'.

Als u een bericht wilt gebruiken dat niet via de parser mag worden verzonden (bijvoorbeeld bij het doorgeven van JSON-gegevens als berichten, of wanneer het bericht wordt gebruikt als vooraf geladen tekst van een pagina), gebruikt u:

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

Opmaak opties

Als u het uitvoerformaat niet aangeeft, geeft mw.message een object Message terug. Om het bericht zelf uit te voeren, moet u een uitvoerformaat aangeven. De formaten zijn meestal hetzelfde als in PHP:

• mw.message( 'foobar' ).plain() Retourneert de berichttekst zoals deze is; alleen parameters worden gesubstitueerd.
• mw.message( 'foobar' ).text() Zet de tekst van het bericht om (alle ondersteunde {{}} blokken worden vervangen door omgezette resultaten). Zie #Functie ondersteuning in JavaScript voor meer informatie over wat wordt ondersteund. Bijvoorbeeld, bepaalde keywords ({{int:}} (maar alleen zonder parameters), {{GENDER}}, {{SITENAME}} enz.) werken, maar transclusie (bijv. {{MediaWiki:}}) en server-zijde Magische woorden zoals {{NUMBEROFEDITS}} of {{ns:Project}} werken niet,
• mw.message( 'foobar' ).escaped() HTML is een geëscapte versie van text.
• mw.message( 'foobar' ).parse() Zet de berichttekst van wikitext om naar HTML. Dit ondersteunt alles in de modus text, als ook de meeste links en maakt de genoemde HTML mogelijk.
• mw.message( 'foobar' ).parseDom() Zoals parse(), maar geeft een jQuery-collectie terug in plaats van een HTML-string.

Waarschuwing:

Als de module mediawiki.jqueryMsg niet wordt geladen, gedragen alle bovenstaande methoden zich in wezen als plain() met mogelijk het escapen.

Er is geen tegenhanger van parseAsBlock. Indien nodig, zet de uitvoer zelf in een blokelement.

Parameters

Parameters kunnen als extra argumenten worden opgegeven voor mw.message(). Ze kunnen worden doorgegeven als string of als DOM-nodes / jQuery-collecties.

Anders dan in PHP, worden de parameters in wikitext niet verwerkt. Effectief gedragen alle parameters met een string zich als plaintextParams().

De DOM/jQuery-parameters kunnen worden gebruikt om het equivalent van rawParams() te bereiken.

Er is geen ondersteuning voor andere formaten van parameters. In plaats van numParams(), moet u nummers formatteren voordat u ze als parameters doorgeeft, met mw.language.convertNumber().

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

Functie ondersteuning in JavaScript

Waarschuwing:

Wikitext-ondersteuning in JavaScript-berichten vereist dat de module mediawiki.jqueryMsg wordt geladen, anders worden deze functies, zonder melding, genegeerd.

JavaScript-berichten ondersteunen slechts een kleine subset van de syntaxis van wikitext. Ondersteunde functies zijn:

• Interne links (behalve truc met het verticale streepje)
• Uitdrukkelijke externe links (geen automatisch genummerde en vrije links)
• De magische woorden SITENAME, PAGENAME, PAGENAMEE, $2, $3, (in 1,38 MediaWiki+) SERVERNAME, (in 1,43 MediaWiki+) CONTENTLANGUAGE
• De parserfuncties PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst
• HTML-tags die in wikitext zijn toegestaan (de HTML moet correct zijn)
• HTML-entiteiten ', ", <, >, &
• De tag ‎<nowiki>

Noemenswaardige wikitekstsyntaxis die niet wordt ondersteund:

• Sjablonen
• Niet-lokale interwiki links
• Alle andere parserfuncties en magische woorden
• Modules (bijvoorbeeld Module:String)
• Alle andere XML-achtige tags (extensie tags)
• Bold en italic ''', '' (gebruik ‎<b>, ‎<i>)
• Lijsten met gebruik van *, # (gebruik ‎<ul> of ‎<ol>, ‎<li>)
• Definitielijsten / indents met ;, : (gebruik ‎<dl>, ‎<dt>, ‎<dd>)
• Meerdere alinea's (gebruik dan ‎<p>)
• Zelf-sluitende HTML-tags
• Opmerkingen <!-- -->
• Sommige soorten van het nesten (bijv. {{PLURAL:$1|<strong>$1</strong>}})

Het sjabloon doc-jqueryMsg kan worden gebruikt om dergelijke berichten te documenteren om vertalers te laten weten welke wikitext-beperkingen van toepassing zijn.

mw.msg

De functie mw.msg() wordt vaak gebruikt als een snelkoppeling voor mw.message().text().

Berichten exporteren via ResourceLoader callbacks

Als u een bericht op de server moet verwerken en het resultaat naar de client moet sturen (bijvoorbeeld omdat u het bericht moet parseren met behulp van parserfuncties die niet worden ondersteund in JavaScript), kunt u dat doen met een packet-bestanden callback in uw ResourceLoader-module. Wanneer u dit doet, zorg er dan voor dat u $context->msg() gebruikt, want als u wfMessage() gebruikt, zal dit fouten veroorzaken.

Berichten in Lua gebruiken

Modules die in Lua zijn geschreven met Scribunto worden op dezelfde manier uitgevoerd als sjablonen en hebben toegang tot MediaWiki-berichten. De MediaWiki Lua bibliotheek bevat de class mw.message voor het verwerken van berichten. Raadpleeg de volledige Lua message library documentatie voor de volledige API. Een eenvoudig voorbeeld:

local p = {}

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- Dit zorgt voor de lokalisatie van nummers
	-- Toon het bericht in de taal van de wiki. frame:preprocess breidt de clausule {{plural}} uit.
	return frame:preprocess( nmembersMsg:plain() )
end

return p

Opmerkingen over gender, grammar, plural

Zie ook Switches in berichten...; De syntaxis zelf is gedocumenteerd op Magische woorden - Lokalisatie en aanverwant.

In het algemeen werken GENDER, GRAMMAR en PLURAL magische woorden op dezelfde manier in zowel PHP als JavaScript.

1. U moet uitvoerformaat text, escaped, parse of parseAsBlock gebruiken om ze te laten werken.
   • In PHP kunt u wfMessage of $this->msg gebruiken.
   • Zorg er in JavaScript voor dat uw resource loader-module afhankelijk is van jqueryMsg (zie Berichten in JavaScript gebruiken).
2. U moet de relevante parameter als normale parameter doorgeven aan het bericht.
   • De parameter is het getal voor PLURAL; de gebruikersnaam in platte tekst of wikitext-escaped voor GENDER in PHP; de sekse uit de voorkeuren of een gebruikersobject voor GENDER in JavaScript (zie hieronder).
   • Voor het inschakelen van lokalisatie van meervoud en correcte nummers in PHP, moet u numParams gebruiken voor het nummer, zie ook Methode ketenen.
   • Om de lokalisatie van plurale en correcte getallen in JavaScript in te schakelen, moet u mw.language.convertNumber gebruiken voor getallen

Voorbeeld syntaxis PLURAL

# Eenvoudig meervoud
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'

GENDER in JavaScript

Dit heeft expliciet jqueryMsg nodig, zie Berichten in JavaScript gebruiken.

Als u in JavaScript een bericht heeft, bijv. "message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article", kunt u het gebruiken zoals hieronder gegeven:

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

In plaats van de GENDER (geslacht) rechtstreeks door te geven, kunnen we elk "gebruiker-achtig" object doorgeven met die optie. Bijvoorbeeld, het huidige gebruikersobject mw.user.

var user = mw.user; // huidige gebruiker
mw.message( 'message-key-gender-foo', user ).text(); // Het opgebouwde bericht zal gebaseerd zijn op het geslacht van de huidige gebruiker.

Indien het geslacht dat is doorgegeven ongeldig of onbekend is, wordt een neutrale vorm gebruikt zoals gedefinieerd voor elke taal. Geef 'unknown' door als u de neutrale vorm wilt hebben.

Als u het geslacht van de huidige gebruiker wilt doorgeven, kunt u een lege string doorgeven:

// de volgende lijn illustreert de berichtinhoud, u kunt deze code draaien op het ontwikkelconsole
mw.messages.set( 'message-key-gender-foo', '{{GENDER:$1|male|female|unknown}}' );
mw.user.options.values.gender = 'female'; // tijdelijk manipuleren van uw voorkeuren hiervoor
mw.message( 'message-key-gender-foo', '' ).text(); // de ontvangen waarde is afhankelijk van uw voorkeur

PLURAL in JavaScript

Dit heeft expliciet jqueryMsg nodig, zie Berichten in JavaScript gebruiken.

Als u in JavaScript een bericht heeft, bijv. 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 items}}' , kunt u het gebruiken zoals hieronder gegeven:

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

Help bij het vervangen van de ontraden functies wfMsg*

Deze functies zijn verwijderd beginnend met MediaWiki 1.27 LTS.

De code die deze functies gebruikt heeft vaak onjuiste vorm van escapen en andere code kwaliteitsproblemen, dus het wordt ook aanbevolen om

• alle functies Xml:: te vervangen door hun Html:: equivalenten, waardoor het makkelijker is om het juiste te doen;
• vermijd waar mogelijk globals en gebruik msg() (zie hierboven);
• vervang htmlspecialchars() door ->escaped() indien van toepassing.

Wijziging code	Beschrijving
In plaats van: wfMsg( 'key' ); schrijf: wfMessage( 'key' )->text();
In plaats van: wfMsgExt( 'key', SOME_FORMAT, 'apple' ); schrijf: wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();	De tweede parameter specificeert de uitvoermodus, meestal als een array zoals array( 'escape' ), maar soms als 'escape': het moet worden vervangen volgens uitvoermodi en escappen, zoals ->escaped().
In plaats van: wfMsgExt( 'key', array( 'parse' ), 'apple' ); schrijf: wfMessage( 'key', 'apple' )->parseAsBlock();	Gebruik volledige parsing en plaats de uitvoer in HTML-tags op blokniveau.
In plaats van: wfMsgExt( 'key', array( 'parseinline' ), 'apple' ); schrijf: wfMessage( 'key', 'apple' )->parse();	Gebruik volledige parsing. Parse-inline wordt gebruikt omdat het nuttiger is bij het vooraf bouwen van HTML. Bij normaal gebruik is het beter om OutputPage::(add|wrap)WikiMsg. te gebruiken.
In plaats van: wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' ); schrijf: wfMessage( 'key', 'apple', 'pear' )->text();	Plaatsen waar HTML niet kan worden gebruikt. {{- De transformatie is klaar.
In plaats van: wfMsgHtml( 'key', 'apple' ); schrijf: wfMessage( 'key' )->rawParams( 'apple' )->escaped();	wfMsgHtml zorgt niet voor escapen van parameters: om hetzelfde resultaat te krijgen moet u rawParams gebruiken; controleer of de parameter echt veilig is voor de HTML-uitvoer. Als het bericht dan als HTML wordt uitgevoerd, moet u escaped() gebruiken voor de beveiliging: het zal ook aan de parameters escappen en dat is niet altijd gewenst, hoewel het er bijvoorbeeld niet toe doet wanneer de parameter een getal is.
In plaats van: wfMsgForContent( 'key' ); schrijf: wfMessage( 'key' )->inContentLanguage()->text();	Een bericht in de inhoudstaal van de wiki krijgen ($wgLanguageCode ).
In plaats van: wfMsgForContentNoTrans( 'key' ); schrijf: wfMessage( 'key' )->inContentLanguage()->plain();	Een bericht in de inhoudstaal van de wiki ($wgLanguageCode ) krijgen maar transformeer het bericht niet.
In plaats van: wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) ); schrijf: wfMessage( 'key' )->inContentLanguage()->isBlank();	Controleert of het 'sleutel'-bericht in de inhoudstaal van de wiki leeg is. Vaak is isDisabled() een meer geschikte controle en moet deze in plaats daarvan worden gebruikt.
In plaats van: wfMsgReal( $error['message'], $error['params'] ); schrijf: ?	Er is geen eenvoudige vervanging, het hangt af van de parameters. Het had nooit gebruikt moeten worden.
In plaats van: wfMsgGetKey schrijf: ?	Er is geen eenvoudige vervanging, het hangt af van de parameters. Het had nooit gebruikt moeten worden.

Zie ook

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