API:Localisation
| MediaWiki Action API |
|---|
| Basics |
| Authentication |
| Accounts and Users |
| Page Operations |
|
| Search |
| Developer Utilities |
| Tutorials |
| v · d · e |
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-summarymessage with a one-line summary of the module and aapihelp-$path-extended-descriptioncontaining 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-descriptionmessage was used. This was be overridden by implementing the getDescriptionMessage() method, but cases where that was needed were rare.
- Prior to 1.30, a
- The parameter description messages, formerly returned by the getParamDescription() method, are
apihelp-$path-param-$name(where$nameis the key from getAllowedParams()). This may be overridden by setting a value forApiBase::PARAM_HELP_MSGin 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_TYPEmay useApiBase::PARAM_HELP_MSG_PER_VALUEto specify that each value is individually documented. These messages are by defaultapihelp-$path-paramvalue-$name-$value. If the messages are named according to the default, there is no need to map messages to values in theApiBase::PARAM_HELP_MSG_PER_VALUEarray (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:
{{doc-apihelp-summary|module path}}{{doc-apihelp-description|module path}}{{doc-apihelp-extended-description|module path}}{{doc-apihelp-param|module path|parameter name}}{{doc-apihelp-paramvalue|module path|parameter name|parameter value}}{{doc-apihelp-paraminfo|module path|parameter info tag name}}{{doc-apihelp-example|module path}}
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. "themax-ageheader" 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 ]- API/Architecture_work/i18n – Draft document from 2014 with information for converting old API modules to the current system.