Handleiding:Messages API
MediaWiki berichten kunnen in de code worden gebruikt via de class Message en de bijbehorende methods.
Hoewel de voorbeelden in dit document de globale functie wfMessage() gebruiken, is het in de meeste gevallen het beste om deze globale functie niet te gebruiken. U moet in plaats daarvan een object gebruiken dat een RequestContext geeft en $context->msg() aanroepen. In veel classes kunt u $this->msg() gebruiken. |
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
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 1st, 2nd, 3rd, 4th, … 11th, 12th, 13th, … 21st, 22nd, 23rd, …
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
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
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[1]text()
- zet de berichttekst (zieMessageCache::transform()
) om die alle{{}}
transformeert, inclusief sjablonen en parserfuncties zoals PLURAL en GENDER, maar zorgt niet voor het escapen of opruimen van de tekstescaped()
- is hetzelfde als 'text', maar zorgt ook voor het escapen voor het gebruik in HTMLparse()
- 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 daarvanHtml::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()
ofHtml::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:[2]
- CategoryViewer
- HTMLForm
- LogEventsList
- DifferenceEngine
- OutputPage
- IndexPager
- ImageHistoryList
- ApiBase
- ChangesList
- Skin
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
- 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
- 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 vantext
.mw.message( 'foobar' ).parse()
Zet de berichttekst van wikitext om naar HTML. Dit ondersteunt alles in de modustext
, als ook de meeste links en maakt de genoemde HTML mogelijk.mw.message( 'foobar' ).parseDom()
Zoalsparse()
, maar geeft een jQuery-collectie terug in plaats van een HTML-string.
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
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, (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.
- U moet uitvoerformaat
text
,escaped
,parse
ofparseAsBlock
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).
- In PHP kunt u wfMessage of
- 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
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
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*
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;[3]
- vermijd waar mogelijk globals en gebruik
msg()
(zie hierboven); - vervang
htmlspecialchars()
door->escaped()
indien van toepassing.
Wijziging code | Beschrijving |
---|---|
In plaats van:
schrijf:
|
|
In plaats van:
schrijf:
|
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() .
|
In plaats van:
schrijf:
|
Use full parsing, and wrap the output in block-level HTML tags. |
In plaats van:
schrijf:
|
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. |
In plaats van:
schrijf:
|
Places where HTML cannot be used. {{-transformation is done. |
In plaats van:
schrijf:
|
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.
|
In plaats van:
schrijf:
|
Get a message in the wiki's content language ($wgLanguageCode ). |
In plaats van:
schrijf:
|
Get a message in the wiki's content language ($wgLanguageCode ) but don't transform the message. |
In plaats van:
schrijf:
|
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.
|
In plaats van:
schrijf:
|
There is no simple replacement, depends on parameters. Should never have been used in the first place. |
In plaats van:
schrijf:
|
There is no simple replacement, depends on parameters. Should never have been used in the first place. |
Zie ook
Opmerkingen
- ↑ Hoewel het mogelijk is om deze modus te gebruiken om HTML-inhoud weer te geven, is het aan te raden om wikitext te gebruiken en de modus parse() te gebruiken om het om te zetten in HTML.
- ↑ Meer in het algemeen, gebruik $this->msg() in niet statische functies van objecten IContextSource.
- ↑ Bijvoorbeeld, er is geen escapen bij Xml::tags().