API:Локализация

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Localisation and the translation is 41% complete.
Outdated translations are marked like this.
Other languages:
Deutsch • ‎Deutsch (Sie-Form) • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎italiano • ‎polski • ‎português do Brasil • ‎română • ‎български • ‎русский • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
Версия MediaWiki:
1.25

Gerrit change 160798

Это документирует данные, специфические для локализации предназначенного для выполнения действий API движка MediaWiki (api.php). См. Localisation для общих комментариев на тему локализации MediaWiki.

Файлы сообщений

Сообщения локализации для ядра MediaWiki содержатся в includes/api/i18n.

Для расширений, сообщения могут быть включены в общих файлах интернационализации или находиться в отдельном файле с использованием обычных механизмов для наличия нескольких файлов. See the localisation documentation about adding new messages.

Сообщения справки

Именование

Сообщения справки по модулям API размещены в пространстве имён с использованием «пути модуля» — строки, используемой для параметра «modules» action=help. Для модулей, добавленных в $wgAPIModules , это будет тот же ключ, как и использованный в этом массиве, когда для модулей, добавленных в $wgAPIPropModules , $wgAPIListModules или $wgAPIMetaModules это будет тот же ключ с префиксом «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.

Документирование сообщений

При документировании сообщений в qqq.json, используйте шаблоны $1, $5, $2, $3 и $4.

Форматирование сообщений

Все сообщения должны заканчиваться точкой и быть грамматически правильными предложениями. Для параметров, передаваемых сообщениям по умолчанию, см. шаблоны, на которые ссылается #Документация сообщений.

Используйте семантическую викитекстовую разметку в сообщениях:

  • ‎<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.

Ошибки и предупреждения

Ошибки генерируются вызовом $this->dieWithError( $messageObjectOrKey );, и сообщение может быть локализовано обычным способом. Тот же принцип действует для предупреждений, используется код $this->addWarning( $messageObjectOrKey );. Подробности на странице API:Errors and warnings. See API:Errors and warnings for details.

Согласно принятым принципам, сообщения об ошибке, генерируемые API, используют ключи сообщений, начинающиеся с apierror-, а предупреждения — ключи, начинающиеся с apiwarn-.

Текст в ответах API

ApiBase, а, значит, и все модули API, также являются контекстными источниками. К сообщениям обычно следует обращаться через $this->msg(), а сам модуль API обычно следует передавать, когда требуется IContextSource.

Сообщения не следует включать в вывод произвольным образом просто по той причине, что клиент может найти их полезными.

Улучшение локализации на сайте translatewiki

Вы можете добавить и улучшить перевода сообщений справки API на translatewiki.net, так же, как и другие сообщения ядра MediaWiki. Соответствующие группы сообщений включают

См. также

  • API/Architecture_work/i18n – Черновик документа с информацией о преобразовании старых модулей API в соответствии с новой системой.