API/Architecture work/i18n

With, API help messages can now be internationalized! This does require some work on the part of extensions; the changes shown here can serve as an example.

Message details
The help messages for API modules are namespaced using the "module path", which is the string used for action=help's "modules" parameter. For modules added to $wgAPIModules this is going to be the same as the key used in that array, while for modules added to $wgAPIPropModules, $wgAPIListModules, or $wgAPIMetaModules it will be that key prefixed with "query+".


 * The description message, formerly returned by the [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a49b8857e40e254e0af27fd281f3a2230 getDescription] method, is . This may be overridden by implementing the [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#aa0c499873fba5c934b98aae65e61a33d getDescriptionMessage] method, but cases where that is needed are rare.
 * The parameter description messages, formerly returned by the [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a1d9406dc4a7b6e5b69554c492ee464f6 getParamDescription] method, are  (where $name is the key from [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]). This may be overridden by setting a value for [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#ab3a6e8b6e7cfbaf4f8bf4339a13d76c5  ] in the data structure returned from [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams].
 * Parameters with a description similar to "When more results are available, use this to continue" should use api-help-param-continue instead of redefining a duplicate message.
 * Sorting parameters taking values "newer" and "older" (with related "start" and "end" parameters) should use api-help-param-direction instead of redefining a duplicate message.
 * Modules using CSRF tokens by implementing [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a9bd9dd747c20665d94b5939373b3f40c ] do not need to document the token parameter; this is automatically handled by ApiBase.
 * Several additional constants are available for use in [//doc.wikimedia.org/mediawiki-core/master/php/html/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]; see ApiBase for details.
 * All examples must have a descriptive text. The method to implement here is getExamplesMessages; see the inline documentation for details. Message names should be along the lines of.

Message formatting
Description and parameter description messages should end with a period, and be grammatical sentences. For parameters passed to the messages by default, see the templates linked from.

Examples should be sentences that could logically end with a colon, but should have no trailing punctuation (this is still under discussion, see below).

If reference to other API modules is needed, pipe a link to Special:ApiHelp and the help formatter will do the right thing. For example, " " is used in the documentation for action=edit's token parameter, and properly renders as an in-page anchored link if both are on the same help page.

Message documentation
When documenting the messages in qqq.json, the templates, , and are recommended.

Still under discussion

 * There is a proposal to use semantic markup (,, , and ) within the documentation; see for details.
 * It's not yet determined whether example descriptions should be ended with a period or left with no trailing punctuation.

Conversion scripts
It can be helpful to extract the existing messages and examples as a starting point, rather than copying everything from scratch. Please contribute any scripts to help with this task here.

Perl, AnomieBOT
With an existing test wiki, this script using the AnomieBOT framework will extract the existing data from the API using action=paraminfo and create various files with the data properly formatted.

Warnings and errors
Planned, see API/Architecture work/Planning.

API output (uselang)
ApiBase has been a subclass of ContextSource since MediaWiki 1.18. Now, in 1.25, uselang is officially recognized by ApiMain. API modules should generally prefer to use $this or $this->getMain as the IContextSource, and  or   when translating messages.

Note that, for backwards-compatability, the API defaults to the user language. may be used in requests when the site's content language is needed.