Manual talk:Messages API

Part about HTML In JavaScript does not make sense
I realize we have to avoid HTML injection, but the advice given here is not practical. It will cause the HTML to be displayed as HTML, which is rarely what you want.

For example, MediaWiki:stub-threshold is a totally straight-forward HTML message with no variables or parser logic. I see no route for injection (the MediaWiki namespace must be restricted to trusted users for many reasons, MediaWiki:Common.js being just one).

Suppose for whatever reason I have to display it using JS. None of the advice works: on the screen.
 * .text will obviously render it as text (this is true regardless of the input)
 * The next two points advise using .escaped. As it sounds like this will escape it so you actually see:

Also, there is no option that parses wikitext to HTML in mw.message, so it can't handle things like MediaWiki:statistics-users (a trivial wikitext message with a link but no variables or PLURAL/GRAMMAR logic).

I'm going to make this more useful, but I'm not dead-set on my wording. In many cases, people are going to have to use plain or parse, but I will keep a note of warning for when it is used with variables. Superm401 - Talk 00:33, 29 December 2012 (UTC)
 * jqueryMsg has more client-side parsing, and I'm working on a patch to implement wikilink parsing (bug 43498). Superm401 - Talk 06:43, 29 December 2012 (UTC)
 * Doesn't this work against 212? --Nemo 10:47, 29 December 2012 (UTC)
 * There are two separate issues.
 * Some messages (e.g. MediaWiki:stub-threshold) are HTML, and at least for now, we need a way to use them on the client-side.
 * Wikitext messages don't work as you expect. You have to use jqueryMsg even to parse e.g. external links, and I have that patch to get basic wikilinks working (let alone bold, italic).  See also 43499 about moving more of the parsing to the server.
 * If wikitext messages worked fully on the client-side, I agree we could (and probably should) use them, and get rendered HTML out of that (in a lot of cases, .text would still be wrong, though). Superm401 - Talk 10:33, 30 December 2012 (UTC)

JavaScript: current situations and future fixes
There are currently plenty of problems with messages in JavaScript; 44459 summarises them and shows how things will have to change. --Nemo 19:38, 10 February 2013 (UTC)

GENDER unclear
In gender notes, it is unclear for PHP if it is ok to use the User object as a parameter, instead of the user name. --Yurik (talk) 03:23, 22 April 2015 (UTC)


 * It takes only Username. Not User object. See CoreParserFunctions::gender --Santhosh.thottingal (talk) 04:42, 22 April 2015 (UTC)

How do I migrate wfMsgHtml
There is this in the code:

By reading all of the docu I figured the following should be the replacement

However this does not work. Any hints? I guess the whole underlying function needs probably to be rewritten since the new system does not seem to handle parameters directly? Cheers --&#91;&#91;kgh&#93;&#93; (talk) 19:59, 12 November 2015 (UTC)
 * "Does not work" is not specific enough for me to help you. Neither is there enough context where you actually pass the result, to say what is the best option. Maybe you forgot the assignment? Or maybe you did not replace 'msg' with 'minnamelength-error'? You can also use the shorter syntax wfMessage( 'minnamelength-error', $wgMinimumUsernameLength )->plain; But you might not want to use plain but maybe escaped. And maybe you can use $this->msg instead. --Nikerabbit (talk) 20:12, 12 November 2015 (UTC)


 * Maybe you want this:
 * --Purodha Blissenbach (talk) 21:08, 12 November 2015 (UTC)


 * Thanks so much for your help! Indeed to write "Does not work" is bull... :( In my solution I actually did replace 'msg' with 'minnamelength-error', so this was a typo here and not the issue. Both solutions, the first one Nike suggested and the one Purodha suggested do work. What puzzles me is that both did not work when I tried them before posting here. That's why I came up with other ways and the third possible solution shown here which did not work either. When I tried them and even other combinations I must have messed up something else since in every case the number passed on by the configuration parameter was not shown or generated [invalid] but only the message string 'minnamelength-error' was there. Using $this->msg caused a fatal so this should not be it. Purodhas solution would allow for counting if I understand correctly so this one is not necessary since only the plain number set with $wgMinimumUsernameLength should be shown. To use text is imho not necessary either since no plural etc. is involved and since no wikitext is involved either parse is not necessary too. So  should be the proper solution. Thanks again for your patience with me and your fast repies! --&#91;&#91;kgh&#93;&#93; (talk) 22:15, 12 November 2015 (UTC)

How to migrate wfMsgReplaceArgs?
What is the new  equivalent for the deprecated function  ? --Djbwiki (talk) 18:12, 13 July 2016 (UTC)
 * It is not deprecated, though I don't recommend its use either. You can achieve the same with  --Nikerabbit (talk) 18:15, 13 July 2016 (UTC)

Deprecated mediawiki.api.messages?
I only want to note that the  seems deprecated. Try to load it and see the console messages. Perhaps we should update the documentation accordingly. --Valerio Bozzolan (talk) 16:18, 30 September 2018 (UTC)

How can we know in which language the message is returned (from fallbacks)?
There's no documented API to know if the language selected by the Message API is the language from which the actual message will be returned (which may be in another fallback language).

This causes problems that cannot be solved easily, notably:
 * when the fallback language uses a different direction than what is expected for the requested language (you can embed the returned message within "bdi" elements to isolate it from a Bidi reordering);
 * for other special formatting that may be needed (e.g. insertion of italics for a message which was only found in a foreign fallback language);
 * for explicitly tagging the message with the correct lang="*" attribute for correct rendering, with the correct fonts suitable for the actual language returned (OpenType fonts may have also language-sensitive rendering for some characters or sequences), or for correct indexing by external sites (including external translation tools that need this explicit information).

We should be able to get that actual language after selecting a target language from the message object, i.e. for which language the message was actually translated. For now it is impossible, applications just assume (incorrectly) that the message is in the language selected.

Can you work on this and add the necessary method on Message objects to return the actual language code that matches in one of the provided translations in some other fallback language (which is also not necessarily English, but could be simplified or traditional Chinese, or Arabic)? This is especially important for correct support of minority languages (which are very frequently partially translated but have their own fallback chain).

For now the only workaround would be to use the fallback API to get the fallback chains, and then resolve these fallbacks before using the Message API, but this does not work when messages are in message bundles i18n data, loaded only from the Message API itself.

Also don't forget to expose this new PHP API into the Lua library (and possibly in the wiki syntax itself, for use along with the  parser function, possibly by an extra parameter indicating we don't want the actual translated message in the specified target language, but just its actual matching language code, and another option requesting that we want only a BCP47 compatible code suitable for HTML lang="" attributes, and not any legacy non-conforming "interwiki" code like "simple" or "sr-el" which may have been used in the provided translation bundles to find a match and that should be replaced respectively by "en-x-simple" or "sr-latn" for strict BCP47 conformance; note that this BCP47 may still be returned in lowercase only and with hyphens instead of underscores, as BCP47 codes can only contain subtags made of ASCII case-insitive letters or digits, separated by hyphens or equivalent underscores) ! Thanks.

Another simplified solution (for more limited uses) would be to have a formatting function that returns the message already encapsulated within a "bdi" element with the correct lang="" attribute (this can only work if the message is intended for inclusion as the "mixed" content of an HTML element, this won't work elsewhere : you can differentiate the use case for HTML with the existing formatting method ; for example, consider what MacOS and iOS is now defining in its localisation API for its "%@" placeholders instead of "%s", where the placeholder is replaced by the variable part within Bidi "isolation" control characters, it cleanly solves the limited but frequent problem with bidirectional texts, such as user names or titles written in variable scripts but encapsulated within translatable sentences; these Bidi controls are not mapped in any font, but recognized since 2013 in MacOS and iOS, directly by the plain-text rendering engine, and in Safari or in the localization API for any application).

Verdy p (talk) 21:01, 6 May 2020 (UTC)

Planning updates to this and related docs
As part of work on the Developer_Advocacy/Developer_Portal, I've been reviewing this page and identifying ways to improve its utility as a landing page / entry point into the localisation / i18n docs. If you're interested in contributing to or staying updated about this work, please reach out or follow https://phabricator.wikimedia.org/T293776 TBurmeister (WMF) (talk) 14:59, 17 November 2021 (UTC)

-- I have now moved content from this page to subpages as outlined in T293776; it's the end of the working day for me now but tomorrow I will review all these changes more closely to try to correct broken links and anchors, and fix other nuances that these major content moves may have made problematic. TBurmeister (WMF) (talk) 22:48, 9 December 2021 (UTC)