From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page API:Localisation and the translation is 35% complete.

Other languages:
български • ‎Deutsch • ‎English • ‎español • ‎français • ‎Հայերեն • ‎日本語 • ‎polski • ‎română • ‎русский • ‎sicilianu • ‎中文
Cette page fait partie de la documentation de l'API MediaWiki.

MediaWiki action API

v · d · e
Version de MediaWiki : 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.

Fiches du message[edit]

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.

Aide messages[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 $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.

Documentation du message[edit]

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

Erreurs et avertissements[edit]

Le code pour ceci doit être encore écrit.

Texte dans les réponses de l'API[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

Voir aussi[edit]