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 this is going to be the same as the key used in that array, while for modules added to, , or  it will be that key prefixed with "query+".


 * The description message, formerly returned by the [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a49b8857e40e254e0af27fd281f3a2230 getDescription] method, is . This may be overridden by implementing the [//doc.wikimedia.org/mediawiki-core/master/php/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/classApiBase.html#a1d9406dc4a7b6e5b69554c492ee464f6 getParamDescription] method, are  (where $name is the key from [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]). This may be overridden by setting a value for [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#ab3a6e8b6e7cfbaf4f8bf4339a13d76c5  ] in the data structure returned from [//doc.wikimedia.org/mediawiki-core/master/php/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/classApiBase.html#a9bd9dd747c20665d94b5939373b3f40c ] do not need to document the token parameter; this is automatically handled by ApiBase.
 * Modules using  should still set it to , but do not need to specify the message for each possible value.
 * Several additional constants are available for use in [//doc.wikimedia.org/mediawiki-core/master/php/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.
 * Note that unlike the previous getExamples function, the query strings should not start with.

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.[check this]

Semantic markup should be used:
 * should be used for mention of parameter keys, and also reference to variables like $wgMiserMode.
 * should be used for the possible values of parameters, and the mention of the input values in example docs.
 * should be used for mention of keys or values in the API output.
 * should be used for anything else that's computer code, e.g. "the  header" or "the page  ".
 * When semantic markup is used, additional quotation marks should not be used.

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. Similarly, reference to MediaWiki configuration variables such as $wgMiserMode should link to the documentation on mediawiki.org.

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

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
With Gerrit change 321406, warnings and errors can now be internationalized too.

Pre-i18n status
On the MediaWiki side, errors and warnings are generally hard-coded strings in English that are passed as-is to existing methods such as  and. ApiBase also has a large number of keys (resembling existing i18n messages) with hard-coded mappings typically accessed via, which may be used directly or may be used when other MediaWiki code attempts to return internationalized messages. When extension code does have an actual i18n message to report as an error, it might break convention by reporting it in the uselang language or it might force English, it might or might not use MediaWiki-namespace customizations, and it might process the message as,  ,  , or   depending on the whim of the original developer.

Clients see warnings as a single string per module, and errors as an associative array with a few properties. In JSON, a response with an error and three warnings might look something like this:

If the underlying code returned multiple errors, only one can be returned.

MediaWiki extension changes
All of the existing ApiBase methods that deal with errors or warnings as strings have been deprecated:,  ,  ,  ,  , and. New ApiBase methods have been introduced to replace them.


 * Instead of  or , code should generally use   now.
 * When dealing with an array of error messages as from, the error array should be passed to the new   method to turn it into a Status object, which should then be passed to the existing   method.
 * Warnings should be reported with  instead of  . Warnings, like errors, now have codes.
 * There's also an  method that can replace the combination of   and.
 * Uses of  should be replaced with , which has been available since MediaWiki 1.25.

For checking user rights, a new method  has been added to ApiBase that will die with an appropriate error message along the lines of "You don't have permission to edit pages", taking advantage of the existing "action-*" messages. For checking permissions on a title,  has been added for the same purpose.

is no longer public (and its format has changed, anyway). Anything that was using it should probably be changed to use an ApiMessage object. Use of  can often be replaced with   or.

The ApiCheckCanExecute hook's  parameter should be set to an ApiMessage, as a string or array return value is now interpreted as an i18n message key rather than a key for. Using an ApiMessage for this hook has been supported since MediaWiki 1.27.

The UsageException class is deprecated in favor of ApiUsageException.
 * ApiUsageException holds a StatusValue object with warnings and errors rather than just a single error. It also records the module that threw the exception.
 * For the time being ApiUsageException is a subclass of UsageException, so code that attempts to catch and handle UsageException should continue to function as it did before.
 * returns the backwards-compatible English plain text, as described below.
 * This should allow unit tests using the  annotation to continue working, although the text tested for may need changing. Also for unit tests, there's a new   method to check the exception by code rather than by text.

Client changes
By default, errors and warnings will continue to be returned in English in the familiar structure. The i18n messages will be processed to wikitext in English without using local MediaWiki-namespace customizations, i.e. . The message's wikitext is then converted to something like plain text by replacing common semantic tags (,, , and ) with double-quotes , removing all other HTML tags without concern for semantics, and replacing HTML entities with the corresponding characters.

Despite this attempt to keep the output generally the same, the actual text of the messages will likely be different. In addition, clients might notice the following changes to API output:
 * Error codes will be different in some situations. Most notably, errors from query submodules will no longer be prefixed like parameters, e.g. prop=revisions will now return badcontinue rather than rvbadcontinue.
 * action=emailuser might return a "Warnings" status now, in case the sending of the email succeeded with warnings. Also, instead of returning an error message as a string message errors and warnings will be returned as arrays errors and warnings.
 * action=imagerotate will now return errors as an array errors rather than a string errormessage.
 * action=move will report errors when moving the talk page as an array talkmove-errors instead of strings talkmove-error-code and talkmove-error-info . Reporting of errors when moving subpages is similarly changed.
 * action=rollback will no longer return a messageHtml property.
 * action=upload will report non-fatal stash errors as an array stasherrors rather than a string stashfailed.

To receive internationalized warnings and errors, the client must specify the new errorformat parameter. The different values of this parameter control whether the errors and warnings are returned as "plaintext" (as described above), wikitext, HTML, or unprocessed message keys and parameters. When error i18n is enabled in this manner, errors and warnings will be returned in the uselang language and will not use MediaWiki-namespace customizations by default. The language may be overridden by using the new errorlang parameter, and MediaWiki-namespace customizations may be enabled by using the errorsuselocal parameter.

Enabling error i18n will also change the format of the errors and warnings in the response. The example above might now look like this:

The internationalization of errors and warnings will also carry over to things such as action=move's talkpage error reporting.

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.