Jump to content
Main menu
Main menu
move to sidebar
hide
Navigation
MainPage
Community portal
Recent changes
Random page
Help
Special pages
Donate
Search
Search
English
Appearance
Log in
Request account
Personal tools
Log in
Request account
Export translations
Translate
English
Language statistics
Message group statistics
Export
Tools
Tools
move to sidebar
hide
Actions
Language statistics
Message group statistics
Export
General
Printable version
In other projects
Appearance
move to sidebar
hide
Settings
Group
Category:Maintenance
Help:Blocking users
Help:Bots
Help:Categories
Help:Contents
Help:Deletion and undeletion
Help:Diff
Help:Editing pages
Help:ExpandTemplates
Help:Extension:ParserFunctions
Help:External searches
Help:Formatting
Help:Images
Help:Links
Help:Magic words
Help:Managing files
Help:Moving a page
Help:Namespaces
Help:Navigation
Help:Parser functions in templates
Help:Patrolled edits
Help:Preferences
Help:Protected pages
Help:Random page
Help:Random root page
Help:Range blocks
Help:Recent changes
Help:Redirects
Help:Skins
Help:Special pages
Help:Starting a new page
Help:Substitution
Help:System message
Help:Tables
Help:Talk pages
Help:TemplateData
Help:Templates
Help:TemplateStyles
Help:Tracking changes
Help:Undelete
Help:User contributions
Help:Watchlist
Help:What links here
Manual:Expr parser function syntax
Manual:Extending wiki markup
Manual:Hooks
Manual:Magic words
Manual:Messages API
Manual:Parser functions
Module:Arguments/doc
Module:Int/doc
Module:Message box/configuration/doc
Module:Message box/doc
Module:Template translation/doc
Module:Transcluder/doc
Module:Version/doc
Module:Yesno/doc
News
Parser extension tags
Parser function extensions
Project:Language policy
Template:Admin tip
Template:Advanced user manual
Template:Anontools
Template:ApiEx
Template:Autocat
Template:Auxiliary template common notice
Template:Branching
Template:Bugfix
Template:Bugzilla
Template:Button
Template:Candidate
Template:Caution
Template:Clarify
Template:Collapse top
Template:Component
Template:Deprecated-inline
Template:Description missing
Template:Distinguish
Template:Documentation
Template:Documentation subpage
Template:Done
Template:EmptyCatGood
Template:Escape template list
Template:Excerpt
Template:Extension development
Template:Fixtext
Template:For
Template:Further
Template:Help
Template:High-risk
Template:Historical
Template:I18n navigation
Template:In progress
Template:Intricate template
Template:Introduced-inline
Template:IRC
Template:Localized link
Template:Localized link/messagedoc
Template:Magic words
Template:Main
Template:MainPage
Template:Markup
Template:Markup/row
Template:Mbox templates
Template:Module rating
Template:Move
Template:MW version
Template:MW version/layout
Template:N/a
Template:Navbar
Template:Newarticletext
Template:No
Template:Not done
Template:Note
Template:Optional
Template:Parser functions nav
Template:Partially done
Template:PD Help Page
Template:Phabricator
Template:Ptag
Template:Purge
Template:Recentchangestext
Template:Removed-inline
Template:Required
Template:Rev
Template:Security
Template:See
Template:See also
Template:Sp-contributions-footer
Template:Sp-contributions-footer-anon
Template:Special page
Template:Template shortcut
Template:Template test cases notice
Template:TemplateData header
Template:Thankyou
Template:To do
Template:Tracked
Template:Translatable
Template:Translatable template name
Template:Unusedtemplatestext
Template:Update
Template:Used in system
Template:Watchlists navigation
Template:Why
Template:WikiNonStop News
Template:Yes
TemplateData
Language
aa - Afar
aae - Arbëresh
ab - Abkhazian
abr - Abron
abs - Ambonese Malay
ace - Acehnese
acf - Saint Lucian Creole
acm - Iraqi Arabic
ady - Adyghe
ady-cyrl - Adyghe (Cyrillic script)
aeb - Tunisian Arabic
aeb-arab - Tunisian Arabic (Arabic script)
aeb-latn - Tunisian Arabic (Latin script)
af - Afrikaans
aig - Antiguan and Barbudan Creole English
aln - Gheg Albanian
alt - Southern Altai
am - Amharic
ami - Amis
an - Aragonese
ang - Old English
ann - Obolo
anp - Angika
apc - Levantine Arabic
ar - Arabic
arc - Aramaic
arn - Mapuche
arq - Algerian Arabic
ary - Moroccan Arabic
arz - Egyptian Arabic
as - Assamese
ase - American Sign Language
ast - Asturian
atj - Atikamekw
av - Avaric
avk - Kotava
awa - Awadhi
ay - Aymara
az - Azerbaijani
azb - South Azerbaijani
ba - Bashkir
ban - Balinese
ban-bali - Balinese (Balinese script)
bar - Bavarian
bbc - Batak Toba
bbc-latn - Batak Toba (Latin script)
bcc - Southern Balochi
bci - Baoulé
bcl - Central Bikol
bdr - West Coast Bajau
be - Belarusian
be-tarask - Belarusian (Taraškievica orthography)
bew - Betawi
bg - Bulgarian
bgc - Haryanvi
bgn - Western Balochi
bh - Bhojpuri
bho - Bhojpuri
bi - Bislama
bjn - Banjar
blk - Pa'O
bm - Bambara
bn - Bangla
bo - Tibetan
bpy - Bishnupriya
bqi - Bakhtiari
br - Breton
brh - Brahui
bs - Bosnian
btm - Batak Mandailing
bto - Rinconada Bikol
bug - Buginese
bug-bugi - Buginese (Buginese script)
bxr - Russia Buriat
ca - Catalan
cbk-zam - Chavacano
ccp - Chakma
cdo - Mindong
cdo-hant - Mindong (Traditional Han script)
cdo-latn - Mindong (Latin script)
ce - Chechen
ceb - Cebuano
ch - Chamorro
chn - Chinook Jargon
cho - Choctaw
chr - Cherokee
chy - Cheyenne
ckb - Central Kurdish
co - Corsican
cop - Coptic
cps - Capiznon
cpx - Puxian
cpx-hans - Puxian (Simplified Han script)
cpx-hant - Puxian (Traditional Han script)
cpx-latn - Puxian (Latin script)
cr - Cree
crh - Crimean Tatar
crh-cyrl - Crimean Tatar (Cyrillic script)
crh-latn - Crimean Tatar (Latin script)
crh-ro - Dobrujan Tatar
cs - Czech
csb - Kashubian
cu - Church Slavic
cv - Chuvash
cy - Welsh
da - Danish
dag - Dagbani
de - German
de-at - Austrian German
de-ch - Swiss High German
de-formal - German (formal address)
dga - Southern Dagaare
din - Dinka
diq - Dimli
dlg - Dolgan
dsb - Lower Sorbian
dtp - Central Dusun
dty - Doteli
dua - Duala
dv - Divehi
dz - Dzongkha
ee - Ewe
efi - Efik
egl - Emilian
el - Greek
eml - Emiliano-Romagnolo
en - English
en-ca - Canadian English
en-gb - British English
eo - Esperanto
es - Spanish
es-419 - Latin American Spanish
es-formal - Spanish (formal address)
et - Estonian
eu - Basque
ext - Extremaduran
fa - Persian
fat - Fanti
ff - Fula
fi - Finnish
fit - Tornedalen Finnish
fj - Fijian
fo - Faroese
fon - Fon
fr - French
frc - Cajun French
frp - Arpitan
frr - Northern Frisian
fur - Friulian
fvr - Fur
fy - Western Frisian
ga - Irish
gaa - Ga
gag - Gagauz
gan - Gan
gan-hans - Gan (Simplified Han script)
gan-hant - Gan (Traditional Han script)
gcf - Guadeloupean Creole
gcr - Guianan Creole
gd - Scottish Gaelic
gl - Galician
gld - Nanai
glk - Gilaki
gn - Guarani
gom - Goan Konkani
gom-deva - Goan Konkani (Devanagari script)
gom-latn - Goan Konkani (Latin script)
gor - Gorontalo
got - Gothic
gpe - Ghanaian Pidgin
grc - Ancient Greek
gsw - Alemannic
gu - Gujarati
guc - Wayuu
gur - Frafra
guw - Gun
gv - Manx
ha - Hausa
hak - Hakka Chinese
hak-hans - Hakka (Simplified Han script)
hak-hant - Hakka (Traditional Han script)
hak-latn - Hakka (Latin script)
haw - Hawaiian
he - Hebrew
hi - Hindi
hif - Fiji Hindi
hif-latn - Fiji Hindi (Latin script)
hil - Hiligaynon
hke - Hunde
hno - Northern Hindko
ho - Hiri Motu
hoc-latn - Ho (Latin script)
hr - Croatian
hrx - Hunsrik
hsb - Upper Sorbian
hsn - Xiang
ht - Haitian Creole
hu - Hungarian
hu-formal - Hungarian (formal address)
hy - Armenian
hyw - Western Armenian
hz - Herero
ia - Interlingua
iba - Iban
ibb - Ibibio
id - Indonesian
ie - Interlingue
ig - Igbo
igl - Igala
ii - Sichuan Yi
ik - Inupiaq
ike-cans - Eastern Canadian (Aboriginal syllabics)
ike-latn - Eastern Canadian (Latin script)
ilo - Iloko
inh - Ingush
io - Ido
is - Icelandic
isv-cyrl - Interslavic (Cyrillic script)
isv-latn - Interslavic (Latin script)
it - Italian
iu - Inuktitut
ja - Japanese
jam - Jamaican Creole English
jbo - Lojban
jut - Jutish
jv - Javanese
ka - Georgian
kaa - Kara-Kalpak
kab - Kabyle
kai - Karekare
kaj - Jju
kbd - Kabardian
kbd-cyrl - Kabardian (Cyrillic script)
kbp - Kabiye
kcg - Tyap
kea - Kabuverdianu
kg - Kongo
kge - Komering
khw - Khowar
ki - Kikuyu
kiu - Kirmanjki
kj - Kuanyama
kjh - Khakas
kjp - Eastern Pwo
kk - Kazakh
kk-arab - Kazakh (Arabic script)
kk-cn - Kazakh (China)
kk-cyrl - Kazakh (Cyrillic script)
kk-kz - Kazakh (Kazakhstan)
kk-latn - Kazakh (Latin script)
kk-tr - Kazakh (Turkey)
kl - Kalaallisut
km - Khmer
kn - Kannada
knc - Central Kanuri
ko - Korean
ko-kp - Korean (North Korea)
koi - Komi-Permyak
kr - Kanuri
krc - Karachay-Balkar
kri - Krio
krj - Kinaray-a
krl - Karelian
ks - Kashmiri
ks-arab - Kashmiri (Arabic script)
ks-deva - Kashmiri (Devanagari script)
ksh - Colognian
ksw - S'gaw Karen
ku - Kurdish
ku-arab - Kurdish (Arabic script)
ku-latn - Kurdish (Latin script)
kum - Kumyk
kus - Kusaal
kv - Komi
kw - Cornish
ky - Kyrgyz
la - Latin
lad - Ladino
lb - Luxembourgish
lbe - Lak
lez - Lezghian
lfn - Lingua Franca Nova
lg - Ganda
li - Limburgish
lij - Ligurian
liv - Livonian
ljp - Lampung Api
lki - Laki
lld - Ladin
lmo - Lombard
ln - Lingala
lo - Lao
loz - Lozi
lrc - Northern Luri
lt - Lithuanian
ltg - Latgalian
lua - Luba-Lulua
lus - Mizo
luz - Southern Luri
lv - Latvian
lzh - Literary Chinese
lzz - Laz
mad - Madurese
mag - Magahi
mai - Maithili
map-bms - Banyumasan
mdf - Moksha
mg - Malagasy
mh - Marshallese
mhr - Eastern Mari
mi - Māori
min - Minangkabau
mk - Macedonian
ml - Malayalam
mn - Mongolian
mnc - Manchu
mnc-latn - Manchu (Latin script)
mnc-mong - Manchu (Mongolian script)
mni - Manipuri
mnw - Mon
mo - Moldovan
mos - Mossi
mr - Marathi
mrh - Mara
mrj - Western Mari
ms - Malay
ms-arab - Malay (Jawi script)
mt - Maltese
mui - Musi
mus - Muscogee
mwl - Mirandese
my - Burmese
myv - Erzya
mzn - Mazanderani
na - Nauru
nah - Nahuatl
nan - Minnan
nan-hant - Minnan (Traditional Han script)
nan-latn-pehoeji - Minnan (Pe̍h-ōe-jī)
nan-latn-tailo - Minnan (Tâi-lô)
nap - Neapolitan
nb - Norwegian Bokmål
nds - Low German
nds-nl - Low Saxon
ne - Nepali
new - Newari
ng - Ndonga
nia - Nias
nit - Southeastern Kolami
niu - Niuean
nl - Dutch
nl-informal - Dutch (informal address)
nmz - Nawdm
nn - Norwegian Nynorsk
no - Norwegian
nod - Northern Thai
nog - Nogai
nov - Novial
nqo - N’Ko
nr - South Ndebele
nrm - Norman
nso - Northern Sotho
nup - Nupe
nv - Navajo
ny - Nyanja
nyn - Nyankole
nyo - Nyoro
nys - Nyungar
oc - Occitan
ojb - Northwestern Ojibwa
olo - Livvi-Karelian
om - Oromo
or - Odia
os - Ossetic
pa - Punjabi
pag - Pangasinan
pam - Pampanga
pap - Papiamento
pap-aw - Papiamento (Aruba)
pcd - Picard
pcm - Nigerian Pidgin
pdc - Pennsylvania German
pdt - Plautdietsch
pfl - Palatine German
pi - Pali
pih - Pitcairn-Norfolk
pl - Polish
pms - Piedmontese
pnb - Western Punjabi
pnt - Pontic
prg - Prussian
ps - Pashto
pt - Portuguese
pt-br - Brazilian Portuguese
pwn - Paiwan
qqq - Message documentation
qu - Quechua
qug - Chimborazo Highland Quichua
rgn - Romagnol
rif - Riffian
rki - Arakanese
rm - Romansh
rmc - Carpathian Romani
rmy - Vlax Romani
rn - Rundi
ro - Romanian
roa-tara - Tarantino
rsk - Pannonian Rusyn
ru - Russian
rue - Rusyn
rup - Aromanian
ruq - Megleno-Romanian
ruq-cyrl - Megleno-Romanian (Cyrillic script)
ruq-latn - Megleno-Romanian (Latin script)
rut - Rutul
rw - Kinyarwanda
ryu - Okinawan
sa - Sanskrit
sah - Yakut
sas - Sasak
sat - Santali
sc - Sardinian
scn - Sicilian
sco - Scots
sd - Sindhi
sdc - Sassarese Sardinian
sdh - Southern Kurdish
se - Northern Sami
se-fi - Northern Sami (Finland)
se-no - Northern Sami (Norway)
se-se - Northern Sami (Sweden)
sei - Seri
ses - Koyraboro Senni
sg - Sango
sgs - Samogitian
sh - Serbo-Croatian
sh-cyrl - Serbo-Croatian (Cyrillic script)
sh-latn - Serbo-Croatian (Latin script)
shi - Tachelhit
shi-latn - Tachelhit (Latin script)
shi-tfng - Tachelhit (Tifinagh script)
shn - Shan
shy - Shawiya
shy-latn - Shawiya (Latin script)
si - Sinhala
simple - Simple English
sjd - Kildin Sami
sje - Pite Sami
sk - Slovak
skr - Saraiki
skr-arab - Saraiki (Arabic script)
sl - Slovenian
sli - Lower Silesian
sm - Samoan
sma - Southern Sami
smn - Inari Sami
sms - Skolt Sami
sn - Shona
so - Somali
sq - Albanian
sr - Serbian
sr-ec - Serbian (Cyrillic script)
sr-el - Serbian (Latin script)
srn - Sranan Tongo
sro - Campidanese Sardinian
ss - Swati
st - Southern Sotho
stq - Saterland Frisian
sty - Siberian Tatar
su - Sundanese
sv - Swedish
sw - Swahili
syl - Sylheti
szl - Silesian
szy - Sakizaya
ta - Tamil
tay - Atayal
tcy - Tulu
tdd - Tai Nuea
te - Telugu
tet - Tetum
tg - Tajik
tg-cyrl - Tajik (Cyrillic script)
tg-latn - Tajik (Latin script)
th - Thai
ti - Tigrinya
tig - Tigre
tk - Turkmen
tl - Tagalog
tly - Talysh
tly-cyrl - Talysh (Cyrillic script)
tn - Tswana
to - Tongan
tok - Toki Pona
tpi - Tok Pisin
tr - Turkish
tru - Turoyo
trv - Taroko
ts - Tsonga
tt - Tatar
tt-cyrl - Tatar (Cyrillic script)
tt-latn - Tatar (Latin script)
ttj - Tooro
tum - Tumbuka
tw - Twi
ty - Tahitian
tyv - Tuvinian
tzm - Central Atlas Tamazight
udm - Udmurt
ug - Uyghur
ug-arab - Uyghur (Arabic script)
ug-latn - Uyghur (Latin script)
uk - Ukrainian
ur - Urdu
uz - Uzbek
uz-cyrl - Uzbek (Cyrillic script)
uz-latn - Uzbek (Latin script)
ve - Venda
vec - Venetian
vep - Veps
vi - Vietnamese
vls - West Flemish
vmf - Main-Franconian
vmw - Makhuwa
vo - Volapük
vot - Votic
vro - Võro
wa - Walloon
wal - Wolaytta
war - Waray
wls - Wallisian
wlx - Wali
wo - Wolof
wuu - Wu
wuu-hans - Wu (Simplified Han script)
wuu-hant - Wu (Traditional Han script)
xal - Kalmyk
xh - Xhosa
xmf - Mingrelian
xsy - Saisiyat
yi - Yiddish
yo - Yoruba
yrl - Nheengatu
yua - Yucatec Maya
yue - Cantonese
yue-hans - Cantonese (Simplified Han script)
yue-hant - Cantonese (Traditional Han script)
za - Zhuang
zea - Zeelandic
zgh - Standard Moroccan Tamazight
zgh-latn - Standard Moroccan Tamazight (Latin script)
zh - Chinese
zh-cn - Chinese (China)
zh-hans - Simplified Chinese
zh-hant - Traditional Chinese
zh-hk - Chinese (Hong Kong)
zh-mo - Chinese (Macau)
zh-my - Chinese (Malaysia)
zh-sg - Chinese (Singapore)
zh-tw - Chinese (Taiwan)
zu - Zulu
Format
Export for off-line translation
Export in native format
Export in CSV format
Fetch
<languages/> {{i18n navigation}} <span lang="en" dir="ltr" class="mw-content-ltr">{{ll|Help:System message|MediaWiki messages}} can be used in the code through the Message class and its associated methods.</span> {{ambox |text = <span lang="en" dir="ltr" class="mw-content-ltr">While the examples throughout this document make use of the global function <code>wfMessage()</code>, in most cases it is best not to use this global function.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Instead, you should use an object that provides a {{ll|Manual:RequestContext.php|RequestContext}}, and call {{phpi|$context->msg()}} on it.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In many classes, you can use {{phpi|$this->msg()}}.</span> }} <div lang="en" dir="ltr" class="mw-content-ltr"> ==Message parameters== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Some messages take parameters.</span> <span lang="en" dir="ltr" class="mw-content-ltr">They are represented by <code>$1</code>, <code>$2</code>, <code>$3</code>, … in the (static) message texts, and replaced at run time.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Typical parameter values are numbers (the "3" in "Delete 3 versions?"), or user names (the "Bob" in "Page last edited by Bob"), page names, links and so on, or sometimes other messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">They can be of arbitrary complexity.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> The list of parameters defined for each specific message is placed in special file "qqq.json" located in "languages/" folder of MediaWiki - read more in [[Special:MyLanguage/Help:System message#Message documentation|Message documentation]]. </div> <span lang="en" dir="ltr" class="mw-content-ltr">It's preferable to use whole words with the PLURAL, GENDER, and GRAMMAR magic words.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, <code><nowiki>{{PLURAL:$1|subpage|subpages}}</nowiki></code> is better than <code><nowiki>sub{{PLURAL:$1|page|pages}}</nowiki></code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It makes searching easier.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> === Referring to other messages === </div> <span lang="en" dir="ltr" class="mw-content-ltr">It's sometimes convenient to refer to sub-messages in a message, e.g. in phrases like "Use the X button" or "Visit the Y page", to ensure that the translations are consistent.</span> <span lang="en" dir="ltr" class="mw-content-ltr">To do so, you may use the following syntax:</span> * <code><nowiki>{{int:X}}</nowiki></code> – <span lang="en" dir="ltr" class="mw-content-ltr">to use the sub-message in interface language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is often used when referring to form buttons or site navigation, e.g. [[MediaWiki:Showpreview|showpreview]].</span> * <code><nowiki>{{MediaWiki:Y}}</nowiki></code> – <span lang="en" dir="ltr" class="mw-content-ltr">to use the sub-message in content language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is used when the sub-message defines a translatable name of a local page, e.g. [[MediaWiki:Mainpage|mainpage]], [[MediaWiki:Grouppage-sysop|grouppage-sysop]], [[MediaWiki:Policy-url|policy-url]].</span> * <code><nowiki>{{#Special:Z}}</nowiki></code> – <span lang="en" dir="ltr" class="mw-content-ltr">to use the name of a special page in content language.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> If you need anything more complicated (e.g. the sub-message used depends on configuration), parse it in your code and pass the whole sub-message as a parameter. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> Example: </div> <syntaxhighlight lang="wikitext"> 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}}]]. </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> ===Switches in messages…=== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Parameters values at times influence the exact wording, or grammatical variations in messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">We don't resort to ugly constructs like "$1 (sub)page(s) of his/her userpage", because these are poor for users and we can do better.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Instead, we make switches that are parsed according to values that will be known at run time.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The static message text then supplies each of the possible choices in a list, preceded by the name of the switch, and a reference to the value that makes a difference.</span> <!--SIC! the link is meant to go to the disambiguation page. The biggest possible overview is desired. --> <span lang="en" dir="ltr" class="mw-content-ltr">This resembles the way {{ll|parser functions}} are called in MediaWiki.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Several types of switches are available.</span> '''<span lang="en" dir="ltr" class="mw-content-ltr">These only work if you do full parsing, or <code><nowiki>{{</nowiki></code>-transformation, for the messages.</span>''' <div lang="en" dir="ltr" class="mw-content-ltr"> ====…on numbers via PLURAL==== </div> <span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki supports plurals, which makes for a nicer-looking product.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example:</span> <syntaxhighlight lang="php"> 'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}', </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> If there is an explicit plural form to be given for a specific number, it is possible with the following syntax: </div> <syntaxhighlight lang="php"> 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.' </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> =====Be aware of PLURAL use on ''all'' numbers===== </div> {{See also|translatewiki:Plural|Help:Magic words#plural}} <span lang="en" dir="ltr" class="mw-content-ltr">When a number has to be inserted into a message text, be aware that some languages will have to use PLURAL on it even if always larger than 1.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The reason is that PLURAL in languages other than English can make very different and complex distinctions, comparable to English 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>, 4<sup>th</sup>, … 11<sup>th</sup>, 12<sup>th</sup>, 13<sup>th</sup>, … 21<sup>st</sup>, 22<sup>nd</sup>, 23<sup>rd</sup>, … ''etc.''</span> <span lang="en" dir="ltr" class="mw-content-ltr">Do not try to supply three different messages for cases like "no items counted", "one item counted", "more items counted".</span> <span lang="en" dir="ltr" class="mw-content-ltr">Rather, let one message take them all, and leave it to translators and PLURAL to properly treat any possible differences of presentation for them in their respective languages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Always include the number as a parameter if possible.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Always add <code><nowiki>{{PLURAL:}}</nowiki></code> syntax to the source messages if possible, even if it makes no sense in English.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The syntax guides translators.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> Fractional numbers are supported, but the plural rules may not be complete. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> =====Pass the number of list items as parameters to messages talking about lists===== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Don't assume that there's only singular and plural.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Many languages have more than two forms, which depend on the actual number used and they have to use [[#…on use context inside sentences via GRAMMAR|grammar]] varying with the number of list items when expressing what is listed in a list visible to readers.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Thus, whenever your code computes a list, include <code>count( $list )</code> as parameter to headlines, lead-ins, footers and other messages about the list, even if the count is not used in English.</span> <span lang="en" dir="ltr" class="mw-content-ltr">There is a neutral way to talk about invisible lists, so you can have links to lists on extra pages without having to count items in advance.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> ====…on user names via GENDER==== </div> <!-- TODO: Integrate this content with the below #Notes about gender, grammar, plural --> <syntaxhighlight lang="php"> 'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.' </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">If you refer to a user in a message, pass the user name as parameter to the message and add a mention in the message documentation that gender is supported.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If it is likely that GENDER will be used in translations for languages with gender inflections, add it explicitly in the English language source message.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> If you directly address the currently logged-in user, leave the user name as parameter empty: </div> <syntaxhighlight lang="php"> 'foobar-logged-in-user' => 'You said {{GENDER:|you were male|you were female|nothing about your gender}}.' </syntaxhighlight> {{MW version|version=1.31|comment=and after|gerrit change=398772}} <div lang="en" dir="ltr" class="mw-content-ltr"> If you include the user name into the message (e.g. <code>{{int|Notification-compact-header-flow-thank}}</code>), consider passing it through <code>wfEscapeWikitext()</code> first, to ensure that characters like <code>*</code> or <code>;</code> are not interpreted. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> =====Users have grammatical genders===== </div> {{See also|translatewiki:Gender|Help:Magic words#gender}} <span lang="en" dir="ltr" class="mw-content-ltr">When a message talks about a user, or relates to a user, or addresses a user directly, the user name should be passed to the message as a parameter.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Thus languages having to, or wanting to, use proper gender dependent grammar, can do so.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This should be done even when the user name is not intended to appear in the message, such as in "inform the user on his/her talk page", which is better made "inform the user on <nowiki>{{GENDER:$1|his|her|their}}</nowiki> talk page" in English as well.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> This does not mean that you are encouraged to "sexualise" messages' language: please use gender-neutral language whenever this can be done with clarity and precision. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> ====…on use context inside sentences via GRAMMAR==== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Grammatical transformations for {{Q|171263|agglutinative language}} is also available.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example for Finnish, where it was an absolute necessity to make language files site-independent, ''i.e.'' to remove the Wikipedia references.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In Finnish, "about Wikipedia" becomes "Tietoja Wikipediasta" and "you can upload it to Wikipedia" becomes "Voit tallentaa tiedoston Wikipediaan".</span> <span lang="en" dir="ltr" class="mw-content-ltr">Suffixes are added depending on how the word is used, plus minor modifications to the base.</span> <span lang="en" dir="ltr" class="mw-content-ltr">There is a long list of exceptions, but since only a few words needed to be translated, such as the site name, we didn't need to include it.</span> <span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki has grammatical transformation functions for over 20 languages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Some of these are just dictionaries for Wikimedia site names, but others have simple algorithms which will fail for all but the most common cases.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Even before MediaWiki had arbitrary grammatical transformation, it had a nominative/genitive distinction for month names.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This distinction is necessary for some languages if you wish to substitute month names into sentences.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> ===Filtering special characters in parameters and messages=== </div> <div lang="en" dir="ltr" class="mw-content-ltr"> The other (much simpler) issue with parameter substitution is HTML escaping. Despite being much simpler, MediaWiki does a pretty poor job of it. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> == Using messages in PHP == </div> {{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">Make sure you always use one of the [[#Output modes and escaping|output modes]] mentioned below</span>}} <div lang="en" dir="ltr" class="mw-content-ltr"> Here is a simple example: </div> <syntaxhighlight lang=php> $out = Xml::submitButton( wfMessage( 'submit' )->text() ); </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr"><code>wfMessage()</code> is a global function which acts as a wrapper for the Message class, creating a Message object.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This example then invokes Message method <code>text()</code> which fetches the text of the <code>submit</code> message in the current language, performs certain language transformations (such as gender and plural), and returns the unescaped message text.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> Here is a more complex example using a message that takes a count and supports linguistic plural handling: </div> <syntaxhighlight lang=php> $out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() ); </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> Don't use the <code>formatnum</code> magic word in messages. Always format the numbers in code. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> The following sections explain the code. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> ===Parameters=== </div> <div lang="en" dir="ltr" class="mw-content-ltr"> Given a message like the following: </div> <syntaxhighlight lang=json> { "msg": "Values are $1, $2" } </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> You pass parameters to messages that need them in several ways: </div> <syntaxhighlight lang=php> wfMessage( 'msg', 'param1', 'param2' )->plain(); wfMessage( 'msg' )->params( 'param1', 'param2' )->plain(); wfMessage( 'msg', [ 'param1', 'param2' ] )->plain(); </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> The first approach is most common, use the second approach when mixing different types of parameters, and you can use the third to construct message objects dynamically from other data. There are ''different types of parameters'': </div> <syntaxhighlight lang="php"> 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+ </syntaxhighlight> ; <code>params()</code> : <span lang="en" dir="ltr" class="mw-content-ltr">Normal message substitution parameter.</span> ; <code>rawParams()</code> : <span lang="en" dir="ltr" class="mw-content-ltr">Substitutes the parameter after the message has been otherwise processed; this means that these parameters are not available to parser functions, nor are they escaped if escaping output format is used (see below).</span> <span lang="en" dir="ltr" class="mw-content-ltr">Make sure you escape them properly yourself.</span> ; <code>plaintextParams()</code> : <span lang="en" dir="ltr" class="mw-content-ltr">Like <code>rawParams()</code>, but does escaping.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It is useful when you pass user input that may contain wikitext that should not be parsed.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Each function from the second group formats the value in a specific way before the substitution.</span> <span lang="en" dir="ltr" class="mw-content-ltr"><code>numParams()</code> must be used if the message uses <code><nowiki>{{PLURAL:}}</nowiki></code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In some cases you might not want to use it even though you have a number, for example a revision ID.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The other functions correspond to Language functions <code>formatDuration</code>, <code>formatExpiry</code>, <code>formatTimePeriod</code>, <code>formatSize</code> and <code>formatBitrate</code>, and are just shorthands for calling them directly.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> ===Language=== </div> <span lang="en" dir="ltr" class="mw-content-ltr">To override the language in which you want the message, there is one method and one shortcut for the common case of using wiki content language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In the latter case you can use either a language code or a language object.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The usual language fallback chains apply, so the actual message you get may be in a different language than requested, if a translation does not exist.</span> <syntaxhighlight lang=php> wfMessage( 'message-key' )->inContentLanguage(); wfMessage( 'message-key' )->inLanguage( $lang ); </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> === Output modes and escaping === </div> <div lang="en" dir="ltr" class="mw-content-ltr"> The Message class, and thus the object returned by wfMessage(), has five output modes: </div> * <code>plain()</code> – <span lang="en" dir="ltr" class="mw-content-ltr">returns the message text as-is; only parameters are substituted</span><ref><span lang="en" dir="ltr" class="mw-content-ltr">While using this mode to display HTML content is possible, it is recommended to use wikitext and use the parse() mode to transform it into HTML.</span></ref> * <code>text()</code> – <span lang="en" dir="ltr" class="mw-content-ltr">transforms the message text (see <code>MessageCache::transform()</code>) which transforms all <code><nowiki>{{}}</nowiki></code> including templates and parser functions like PLURAL and GENDER, but neither escapes nor sanitizes</span> * <code>escaped()</code> – <span lang="en" dir="ltr" class="mw-content-ltr">same as 'text', but also escapes it for use in HTML</span> * <code>parse()</code> – <span lang="en" dir="ltr" class="mw-content-ltr">parses the message text from wikitext to HTML and sanitizes (MessageCache::parse() which calls the Parser)</span> * <code>parseAsBlock()</code> – <span lang="en" dir="ltr" class="mw-content-ltr">the output is wrapped in a block level HTML element, if not already, similarly to OutputPage::addWikiMsg</span> <span lang="en" dir="ltr" class="mw-content-ltr">Remember that [[Special:MyLanguage/manual:Html.php|Html::]] functions escape everything fed into them, so use the text() format with those to avoid double escaping.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Hence the most common output format is text().</span> <span lang="en" dir="ltr" class="mw-content-ltr">Also, make sure to use parse() or parseAsBlock() if the message has wikitext in it, otherwise the wikitext will just be escaped and output as plain text.</span> <span lang="en" dir="ltr" class="mw-content-ltr">When using <code>wfMessage()</code> or {{phpi|$this->msg()}}, you should always specify an output type.</span> <span lang="en" dir="ltr" class="mw-content-ltr"><code>text()</code> is appropriate when you're outputting it through <code>addWikiText()</code>.</span> <div lang="en" dir="ltr" class="mw-content-ltr"> ==== Which output mode to use ==== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Generally speaking, the most common modes you will use are <code>->parse()</code> and <code>->text()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You use ->parse() in most places where HTML markup is supported, and you use <code>->text()</code> in places where the content is going to become HTML escaped or HTML markup is not supported.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Some common cases:</span> * <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting the message in the text part (third argument) of {{phpi|Html::element}} use <code>->text()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You may also consider using {{phpi|Html::rawElement()}} instead and using the <code>->parse()</code> mode.</span> * <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting in text (third argument) of {{phpi|Html::rawElement()}}, you should generally use <code>->parse()</code>.</span> * <span lang="en" dir="ltr" class="mw-content-ltr">If you are putting into the attributes (second argument) of {{phpi|Html::rawElement()}} or {{phpi|Html::element()}}, use <code>->parse()</code></span> * <span lang="en" dir="ltr" class="mw-content-ltr">If you are manually constructing HTML attributes, you should use <code>->escaped()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">However you should never manually construct HTML attributes</span> * <span lang="en" dir="ltr" class="mw-content-ltr">For {{phpi|$out->addWikiText()}} where <code>$out</code> is an OutputPage object use <code>->text()</code> or <code>->plain()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">However consider if you would rather use {{phpi|$out->addWikiMsg}} instead.</span> * <span lang="en" dir="ltr" class="mw-content-ltr">For $out->addHTML() use <code>->parse()</code></span> {{anchor|Chaining}} <div lang="en" dir="ltr" class="mw-content-ltr"> ===Method chaining=== </div> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is called '''method chaining'''.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Here is an example:</span> <syntaxhighlight lang="php"> wfMessage( 'key' ) ->params( 'apple' ) ->numParams( $numOfApples ) ->setContext( $context ) ->inContentLanguage() ->parse() </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> === Additional methods of printing messages === </div> <span lang="en" dir="ltr" class="mw-content-ltr">The general message function in MediaWiki is <code>wfMessage</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">'''OutputPage''' has a few methods that append directly to the generated output.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The useful ones are:</span> <syntaxhighlight lang=php> $out->addWikiMsg( 'pageheader' ); $out->wrapWikiMsg( '<div class="error">\n$1\n</div>', [ 'someerrormessage', $user->getName() ] ); </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">Both of the above parse the wikitext in the context of the current page before appending it to output buffer.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Classes extending '''ContextSource''' have a method <code>msg</code> that automatically sets the current context (language, current page etc.).</span> <span lang="en" dir="ltr" class="mw-content-ltr">It is therefore recommended to use {{phpi|$this->msg()}} for those classes, like '''special pages'''.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Here is a non-exhaustive list of such classes:</span><ref><span lang="en" dir="ltr" class="mw-content-ltr">More in general, use $this->msg() in non-static functions of IContextSource objects.</span></ref> * CategoryViewer * HTMLForm * LogEventsList * DifferenceEngine * OutputPage * IndexPager * ImageHistoryList * ApiBase * ChangesList * Skin {{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">The QuickTemplate class and its subclasses (BaseTemplate) have a method named <code>msg</code> which is different from the one from ContextSource.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In these classes $this->msg() will simply output the escaped text of the message.</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">Examples of '''correct''' usage:</span> <syntaxhighlight lang="PHP"> wfMessage( 'key' )->numParams( 567 )->text(); $this->msg( 'key' )->numParams( 567 )->parse(); </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">Examples of '''incorrect''' usage:</span> <syntaxhighlight lang="PHP"> wfMessage( 'key', 345 )->parseInline(); # Number is not formatted correctly $this->msg( 'key', 345 )->numParams( 234 )->plain() # Plural syntax is not converted in plain format </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> == Using messages in JavaScript == </div> {{See also|ResourceLoader/Core_modules#mw.message|label 1=ResourceLoader/Core modules#mediaWiki.message}} :{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This page only deals with MediaWiki core.</span> <span lang="en" dir="ltr" class="mw-content-ltr">See the specific documentation instead for the [https://github.com/wikimedia/jquery.i18n#jqueryi18n '''jquery.i18n'''] module.</span>}} <div lang="en" dir="ltr" class="mw-content-ltr"> === Getting the messages to the client === </div> <span lang="en" dir="ltr" class="mw-content-ltr">To use the messages, we need to make sure that the messages are available at client side first.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This can be done using either a ResourceLoader module (most common) or an API query from JavaScript (rare).</span> <div lang="en" dir="ltr" class="mw-content-ltr"> ==== Using a ResourceLoader module ==== </div> {{See also|Special:MyLanguage/Manual:$wgResourceModules|label 1=Manual:$wgResourceModules}} : {{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This is the most common method of delivering messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You should use this unless you have a good reason not to.</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">We are going to use [[Special:MyLanguage/ResourceLoader|ResourceLoader]] to make sure that the messages are available at the client side.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For this, in your ResourceLoader modules, define the messages to be exported to the client side.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If you plan to use the <code>mw.message(…).parse()</code> to generate HTML from wikitext in interface messages, then it is important to load the [[Special:MyLanguage/ResourceLoader/Core_modules#mediawiki.jqueryMsg|mediawiki.jqueryMsg]] module.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Example (extension.json):</span> <syntaxhighlight lang=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" ] } } } </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> ==== Using an API query from JavaScript ==== </div> :{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This is not a common way of loading messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You should only use this if there is a good reason why you can't use [[#Using a ResourceLoader module|the ResourceLoader module method above]].</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">You can use the following code:</span> {{MW 1.27|and later}} <syntaxhighlight lang="javascript"> // When: The 'mediawiki.api' module is loaded, and, the page is ready $.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready ) // Then: Load the messages that you need (if they are not yet loaded) .then( () => new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] ) ) // Then: Do stuff with them .then( doStuff ); </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">To get the messages in some language other than the <code>UserLanguage</code> language, use getMessages instead of loadMessagesIfMissing, and supply the target language as the "amlang" field of the optional second parameter, like so:</span> <syntaxhighlight lang="javascript"> // 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( () => new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' } ) ) // Then: Do stuff with them .then( doStuff ); // doStuff is a function that will receive as its first parameter an object that looks like so: // { february: "février", january: "janvier", march: "mars" } </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> === Use of the messages === </div> <span lang="en" dir="ltr" class="mw-content-ltr">The messages defined in the above example will be available at client side and can be accessed by <code>mw.message( 'message-key-name' )</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example:</span> $( {{code-string|'<div>'}} ).{{bgc|#ffb6db|text}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|text}}() ); <span lang="en" dir="ltr" class="mw-content-ltr">Note how we use jQuery <code>{{bgc|#ffb6db|text}}</code> method to escape our output properly when using mw.message <code>{{bgc|#6db6ff|text}}</code> format.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If your message contains wikitext formatting, you can instead use the following:</span> $( {{code-string|'<div>'}} ).{{bgc|#ffb6db|append}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|parseDom}}() ); <span lang="en" dir="ltr" class="mw-content-ltr">Here we use jQuery <code>{{bgc|#ffb6db|append}}</code> method to insert the DOM nodes returned by mw.message <code>{{bgc|#6db6ff|parseDom}}</code> format.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In older code you might also encounter the following: (<code>parseDom</code> was not available until MediaWiki 1.27)</span> $( {{code-string|'<div>'}} ).{{bgc|#ffb6db|html}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|escaped}}() ); $( {{code-string|'<div>'}} ).{{bgc|#ffb6db|html}}( mw.message( {{code-string|'translate-msggroupselector-projects'}} ).{{bgc|#6db6ff|parse}}() ); <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">We can also pass the dynamic parameters to the message (i.e. the values for $1, $2, etc.) as shown below.</span> <syntaxhighlight lang="javascript"> $( '<div>' ).text( mw.message( 'hello-user', username ).text() ); </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">In the above examples, note that the message should be defined in an i18n file.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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 <code>⧼message-key-foo⧽</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In older versions of MediaWiki, the message key was returned in ASCII angle brackets, like <code><message-key-foo></code>, and this could generate invalid or fake HTML elements.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In the case where the message key does not exists, the <code>.exists()</code> method of the returned message object will also return false instead of true.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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 [[Special:MyLanguage/Manual:Creating pages with preloaded text|preloaded text]] of a page), use:</span> <syntaxhighlight lang="javascript"> mw.message( 'foobar' ).plain() </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> ==== Format options ==== </div> <span lang="en" dir="ltr" class="mw-content-ltr">If you don't specify the output format, mw.message just returns a Message object.</span> <span lang="en" dir="ltr" class="mw-content-ltr">To output the message itself, you should specify an output format.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The formats are mostly the same as in PHP side:</span> * <code>mw.message( 'foobar' ).plain()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Returns the message text as-is; only parameters are substituted.</span> * <code>mw.message( 'foobar' ).text()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Transforms the message text (all supported <code><nowiki>{{}}</nowiki></code> blocks are replaced with transformed results).</span> <span lang="en" dir="ltr" class="mw-content-ltr">See [[#Feature support in JavaScript|#Feature support in JavaScript]] for details of what is supported.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, certain keywords (<code><nowiki>{{int:}}</nowiki></code>, <code><nowiki>{{GENDER}}</nowiki></code>, <code><nowiki>{{SITENAME}}</nowiki></code> etc.) work without parameters, but tranclusion (e.g. <code><nowiki>{{MediaWiki:}}</nowiki></code>) and server-side [[Special:MyLanguage/Help:Magic words|Magic words]] such as <nowiki>{{NUMBEROFEDITS}}</nowiki> or <nowiki>{{ns:Project}}</nowiki> do not work,</span> * <code>mw.message( 'foobar' ).escaped()</code> <span lang="en" dir="ltr" class="mw-content-ltr">HTML escaped version of <code>text</code>.</span> * <code>mw.message( 'foobar' ).parse()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Parses the message text from wikitext to HTML.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This supports everything from <code>text</code> mode, as well as most links, and allow listed HTML.</span> *<code>mw.message( 'foobar' ).parseDom()</code> <span lang="en" dir="ltr" class="mw-content-ltr">Like <code>parse()</code>, but returns a jQuery collection instead of a HTML string.</span> {{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">If the mediawiki.jqueryMsg module is not loaded, all of the above methods behave essentially like <code>plain()</code> with possible escaping.</span>}} {{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">There is no equivalent of parseAsBlock.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Where necessary, wrap the output in a block element yourself.</span>}} <div lang="en" dir="ltr" class="mw-content-ltr"> ==== Parameters ==== </div> <span lang="en" dir="ltr" class="mw-content-ltr">Parameters can be specified as additional arguments to <code>mw.message()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">They can be passed as strings or as DOM nodes / jQuery collections.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Unlike in PHP, wikitext in the parameters is ''not parsed''.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Effectively, all string parameters behave like <code>plaintextParams()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">DOM/jQuery parameters can be used to achieve the equivalent of <code>rawParams()</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">There is no support for other parameter formats.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Don't use the <code>formatnum</code> magic word in messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Always format the numbers in code.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In JavaScript, instead of <code>numParams()</code>, you must format numbers before passing them as parameters, using <code>mw.language.convertNumber()</code>.</span> <syntaxhighlight lang="javascript"> $( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() ); </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> === Feature support in JavaScript === </div> {{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">Wikitext support in JS messages requires the <code>mediawiki.jqueryMsg</code> module to be loaded, otherwise these features will be silently ignored.</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">JavaScript messages only support a small subset of wikitext syntax. Supported features include:</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Internal links (except [[Special:MyLanguage/pipe trick|pipe trick]])</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Explicit external links (no auto-numbered and free links)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">The magic words SITENAME, PAGENAME, PAGENAMEE; since MW 1.38: SERVERNAME; since MW 1.43: CONTENTLANGUAGE</span> * <span lang="en" dir="ltr" class="mw-content-ltr">The parser functions PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst; since MW 1.44: fullurl</span> * <span lang="en" dir="ltr" class="mw-content-ltr">HTML tags which are allowed in wikitext (HTML must be well-formed)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">HTML entities <code>&#039;</code>, <code>&quot;</code>, <code>&lt;</code>, <code>&gt;</code>, <code>&amp;</code></span> * <span lang="en" dir="ltr" class="mw-content-ltr">The {{tag|nowiki|open}} tag</span> <span lang="en" dir="ltr" class="mw-content-ltr">Notable wikitext syntax that is '''not''' supported:</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Templates</span> * <span lang="en" dir="ltr" class="mw-content-ltr">[[metawiki:Special:MyLanguage/Help:Interwiki_linking#Non-local_interwikis|Non-local interwiki links]]</span> * <span lang="en" dir="ltr" class="mw-content-ltr">All other parser functions and magic words</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Modules (for example [[Special:MyLanguage/Module:String|Module:String]])</span> * <span lang="en" dir="ltr" class="mw-content-ltr">All other XML-like tags (extension tags)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Bold and italic <code><nowiki>'''</nowiki></code>, <code><nowiki>''</nowiki></code> (use {{tag|b|open}}, {{tag|i|open}} instead)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Lists using <code>*</code>, <code>#</code> (use {{tag|ul|open}} or {{tag|ol|open}}, {{tag|li|open}} instead)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Definition lists / indents using <code>;</code>, <code>:</code> (use {{tag|dl|open}}, {{tag|dt|open}}, {{tag|dd|open}} instead)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Multiple paragraphs (use {{tag|p|open}} instead)</span> * <span lang="en" dir="ltr" class="mw-content-ltr">Comments</span> <syntaxhighlight lang=html inline><!-- --></syntaxhighlight> * <span lang="en" dir="ltr" class="mw-content-ltr">Some types of nesting (e.g. <syntaxhighlight lang="html" inline>{{PLURAL:$1|<strong>$1</strong>}}</syntaxhighlight>)</span> <div lang="en" dir="ltr" class="mw-content-ltr"> The [[translatewiki:Template:Doc-jqueryMsg|doc-jqueryMsg template]] can be used to [[Special:MyLanguage/Help:System message#Message documentation|document]] such messages, to let translators know which wikitext restrictions apply. </div> === mw.msg === <div lang="en" dir="ltr" class="mw-content-ltr"> The <code>mw.msg()</code> function is commonly used as a shortcut for <code>mw.message().text()</code>. </div> <div lang="en" dir="ltr" class="mw-content-ltr"> === Exporting messages through ResourceLoader callbacks === </div> <span lang="en" dir="ltr" class="mw-content-ltr">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 [[ResourceLoader/Package files#Generated_content|package files callback]] in your ResourceLoader module.</span> <span lang="en" dir="ltr" class="mw-content-ltr">When you do this, take care to use {{phpi|$context->msg()}}, because using <code>wfMessage()</code> will [[Special:MyLanguage/ResourceLoader/Package files#Common pitfall: using i18n messages in generated content callbacks|cause errors]].</span> <div lang="en" dir="ltr" class="mw-content-ltr"> == Using messages in Lua == </div> <span lang="en" dir="ltr" class="mw-content-ltr">Modules written in Lua using {{ll|Extension:Scribunto|Scribunto}} run similarly to templates and have access to MediaWiki messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The MediaWiki Lua library includes the mw.message class for processing messages.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Refer to the full [[Special:MyLanguage/Extension:Scribunto/Lua reference manual#Message library|Lua message library]] documentation for the full API.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Here is a simple example:</span> <syntaxhighlight lang="lua"> 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 </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> == Using messages in Vue.js == </div> {{See also|Vue.js#Internationalization}} <div lang="en" dir="ltr" class="mw-content-ltr"> == Notes about gender, grammar, plural == </div> : <span lang="en" dir="ltr" class="mw-content-ltr">See also [[#Switches in messages…|#Switches in messages…]]; the syntax itself is documented at [[Special:MyLanguage/Help:Magic words#Localization|Help:Magic words#Localization]] and related.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In general, GENDER, GRAMMAR and PLURAL magic words work identically in both PHP and JavaScript sides.</span> # <span lang="en" dir="ltr" class="mw-content-ltr">You must use <code>text</code>, <code>escaped</code>, <code>parse</code> or <code>parseAsBlock</code> [[#Output modes and escaping|output formats]] for them to work.</span> #* <span lang="en" dir="ltr" class="mw-content-ltr">In PHP, you can use wfMessage or <code>[[#Additional methods of printing messages|$this->msg]]</code>.</span> #* <span lang="en" dir="ltr" class="mw-content-ltr">In JavaScript, make sure your resource loader module depends on <code>jqueryMsg</code> (see [[#Using messages in JavaScript|#Using messages in JavaScript]]).</span> # <span lang="en" dir="ltr" class="mw-content-ltr">You need to pass the relevant parameter as normal parameter to the message.</span> #* <span lang="en" dir="ltr" class="mw-content-ltr">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 ([[#GENDER in JavaScript|see below]]).</span> #* <span lang="en" dir="ltr" class="mw-content-ltr">For enabling plural and correct number localization in PHP, you need to use <code>numParams</code> for the number, see also [[#Chaining|#Chaining]].</span> #* <span lang="en" dir="ltr" class="mw-content-ltr">For enabling plural and correct number localization in JavaScript, you need to use <code>mw.language.convertNumber</code> for the number</span> <div lang="en" dir="ltr" class="mw-content-ltr"> === PLURAL syntax example === </div> <syntaxhighlight lang="PHP"> # Simple plural 'key' => '$1 crying {{PLURAL:$1|baby|babies}}' </syntaxhighlight> {{anchor|JavaScript examples}} <div lang="en" dir="ltr" class="mw-content-ltr"> === GENDER in JavaScript === </div> {{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This needs explicit <code>jqueryMsg</code>, see [[#Using messages in JavaScript|#Using messages in JavaScript]].</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">If you have a message, say, <code><nowiki>"message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article"</nowiki></code>, in JavaScript, you can use it as given below:</span> <syntaxhighlight lang=javascript> 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' </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">Instead of passing the gender directly, we can pass any "User-like" object with a gender option.</span> <span lang="en" dir="ltr" class="mw-content-ltr">For example, the current user object <code>mw.user</code>.</span> <syntaxhighlight lang=javascript> 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. </syntaxhighlight> <span lang="en" dir="ltr" class="mw-content-ltr">If the gender passed is invalid or unknown, the gender neutral form will be used as defined for each language.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Pass <code>'unknown'</code> if you intentionally want the neutral form.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Finally, if you want to use the gender of the current user, you can pass an empty string:</span> <syntaxhighlight lang=javascript> // 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 </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> === PLURAL in JavaScript === </div> {{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This needs explicit <code>jqueryMsg</code>, see [[#Using messages in JavaScript|#Using messages in JavaScript]].</span>}} <span lang="en" dir="ltr" class="mw-content-ltr">If you have a message, say <code><nowiki> 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 items}}' </nowiki></code> , in JavaScript, you can use it as given below:</span> <syntaxhighlight lang=javascript> mw.message( 'message-key-plural-foo', count ).text(); // returns 'There is 1 item' if count = 1 // returns 'There are 6 items' if count = 6 </syntaxhighlight> <div lang="en" dir="ltr" class="mw-content-ltr"> == See also == </div> * {{ll|API:Allmessages}} * {{ll|Help:HTML_in_wikitext}} * [[wmdoc:mediawiki-core/master/php/classMessage.html|<span lang="en" dir="ltr" class="mw-content-ltr">Message class documentation</span>]] <div lang="en" dir="ltr" class="mw-content-ltr"> ==Notes== </div> <references/> {{Parser functions nav}} [[Category:MediaWiki code{{#translation:}}]] [[Category:Localisation{{#translation:}}]]
Search
Search
Export translations
Add topic