API:Localisation

From mediawiki.org
MediaWiki version:
1.25
Gerrit change 160798

This documents things specific to localisation of the MediaWiki action API (api.php). See Localisation for general comments on MediaWiki localisation.

Message files[edit]

Localisation messages for MediaWiki core are located under includes/api/i18n.

For extensions, the messages that are only used for API documentation and aren't seen by most end users should be in a separate file using the normal mechanisms for having multiple files. See the localisation documentation about adding new messages.

Help messages[edit]

Naming[edit]

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 getDescription() method, has been split into two: a apihelp-$path-summary message with a one-line summary of the module and a apihelp-$path-extended-description containing any additional module-level documentation. These may be overridden with corresponding methods, but cases where that is needed are rare.
    • Prior to 1.30, a apihelp-$path-description message was used. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
  • The parameter description messages, formerly returned by the getParamDescription() method, are apihelp-$path-param-$name (where $name is the key from getAllowedParams()). This may be overridden by setting a value for ApiBase::PARAM_HELP_MSG in the data structure returned from 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 needsToken() do not need to document the token parameter; this is automatically handled by ApiBase.
    • Several additional constants are available for use in getAllowedParams(); see ApiBase for details.
  • Parameters with an array for ApiBase::PARAM_TYPE may use ApiBase::PARAM_HELP_MSG_PER_VALUE to specify that each value is individually documented. These messages are by default apihelp-$path-paramvalue-$name-$value. If the messages are named according to the default, there is no need to map messages to values in the ApiBase::PARAM_HELP_MSG_PER_VALUE array (it still has to exist but can be left empty).
  • All examples must have a descriptive text. Message names should be along the lines of apihelp-$path-example-$arbitrarySuffix.

Message documentation[edit]

When documenting the messages in qqq.json, use the following templates:

Message formatting[edit]

All messages should end with a period, and be grammatical sentences. For parameters passed to the messages by default, see the templates linked from #Message documentation.

Use semantic wikitext markup in messages:

  • ‎<var> for mention of parameter keys, and also references to variables like $wgMiserMode.
  • ‎<kbd> for the possible values of parameters, mention of parameters with values (including references to other modules), and the mention of the input values in example docs.
  • ‎<samp> for mention of keys or values in the API output.
  • ‎<code> for anything else that's computer code, e.g. "the max-age header" or "the page ‎<head>".
  • You don't need additional quotation marks when using semantic markup.

If you need to reference other API modules, pipe a link to Special:ApiHelp and the help formatter will do the right thing. For example, "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]" is used in the documentation for various token parameters. The Special:ApiHelp link properly renders as an in-page anchored link if it's on the same help page (example). Similarly, reference to MediaWiki configuration variables such as $wgMiserMode should link to the documentation on mediawiki.org.

Pages referenced in examples should generally not be linked, as these links are unlikely to exist on many wikis.

Errors and warnings[edit]

Errors are raised by calling $this->dieWithError( $messageObjectOrKey ); and the message can be localized in the usual way. Likewise for warnings with $this->addWarning( $messageObjectOrKey );. See API:Errors and warnings for details.

Customarily API error messages have message keys starting with apierror- and warnings with apiwarn-. You can use {{doc-apierror}} in the message documentation.

Text in API responses[edit]

ApiBase, and thus all API modules, are also context sources. Messages should generally be accessed using $this->msg(), and the API module itself should generally be passed when an IContextSource is needed.

Messages should not be arbitrarily included in the output because a client might find it useful.

Improving localisations on translatewiki[edit]

You can add and improve API help message translations on translatewiki.net, in the same manner as other core MediaWiki messages. The relevant message groups include

See also[edit]