API:Localisation

---

This page is part of the MediaWiki action API documentation.

MediaWiki APIsAPI:Main page

• Web APIs showcaseAPI:Web APIs hub
• REST content API

MediaWiki action API

• Introduction and quick startAPI:Main page
• FAQAPI:FAQ
  • Etiquette and usage limitsAPI:Etiquette
• TutorialAPI:Tutorial
• FormatsAPI:Data formats
• Error reportingAPI:Errors and warnings
• Restricting usageAPI:Restricting API usage
• Cross-site requestsAPI:Cross-site requests
• Authentication
  • LoginAPI:Login
  • LogoutAPI:Logout
  • Account creationAPI:Account creation
• QueriesAPI:Query
  • Meta informationAPI:Meta
  • PropertiesAPI:Properties
  • ListsAPI:Lists
• Searching (by title, content, coordinates...)API:Search and discovery
• Parsing wikitext and expanding templatesAPI:Parsing wikitext
• Purging pages' cachesAPI:Purge
• Parameter informationAPI:Parameter information
• Changing wiki contentAPI:Changing wiki content
  • Create and edit pagesAPI:Edit
  • Move pagesAPI:Move
  • RollbackAPI:Rollback
  • Delete pagesAPI:Delete
  • Restore deleted revisionsAPI:Undelete
  • (Un)protect pagesAPI:Protect
  • (Un)block usersAPI:Block
  • (Un)watch pagesAPI:Watch
  • Mark revisions of watched pages as visitedAPI:SetNotificationTimestamp
  • Send emailAPI:Email
  • Patrol changesAPI:Patrol
  • Import pagesAPI:Import
  • Change user group membershipAPI:User group membership
  • Upload filesAPI:Upload
  • User optionsAPI:Options
  • TokensAPI:Tokens
  • Page languageAPI:PageLanguage
• Watchlist feedAPI:Watchlist feed
• WikidataWikibase/API
• ExtensionsAPI:Extensions
• Using the API in MediaWiki and extensionsAPI:Calling internally
• MiscellaneousAPI:Other services
• ImplementationAPI:Implementation Strategy
  • LocalisationAPI:Localisation
• Client codeAPI:Client code
• AssertingAPI:Assert

MediaWiki version:

≥ 1.25 Gerrit change 160798

This documents things specific to localisation of the MediaWiki web API (api.php).

See Localisation for general comments on MediaWiki localisation.

Message files

Localisation messages for MediaWiki core are located under includes/api/i18n. For extensions, the messages may be included in the general i18n files or may be in a separate file using the normal mechanisms for having multiple files.

Help messages

Naming

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 $wgAPIModulesManual:$wgAPIModules this is going to be the same as the key used in that array, while for modules added to $wgAPIPropModulesManual:$wgAPIPropModules, $wgAPIListModulesManual:$wgAPIListModules, or $wgAPIMetaModulesManual:$wgAPIMetaModules it will be that key prefixed with "query+".

• The description message, formerly returned by the getDescription() method, is apihelp-$path-description. This may be overridden by implementing the getDescriptionMessage() method, but cases where that is needed are 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.
• All examples must have a descriptive text. Message names should be along the lines of apihelp-$path-example-$arbitrarySuffix.

Message documentation

When documenting the messages in qqq.json, use the templates {{doc-apihelp-description|module path}}, {{doc-apihelp-param|module path|parameter name}}, {{doc-apihelp-paramvalue|module path|parameter name|parameter value}}, and {{doc-apihelp-example|module path}}.

Message formatting

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, 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

The code for this has yet to be written.

Text in API responses

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

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

• MediaWiki web API
• API feature usage
• ApiSandbox extension

See also

• API/Architecture_work/i18n – Draft document with information for converting old API modules to the new system.
• translatewiki:Template:doc-apihelp-param