API:Localisation/zh

Category:MediaWiki action API/zh
MediaWiki版本：
≥ 1.25
Gerrit change 160798

本文檔專門介紹了MediaWiki操作API（api.php）的本地化的相關內容。 請参见本地化以获取MediaWiki本地化上的一般注释。

消息文件

MediaWiki 核心的在地化訊息位於 includes/api/i18n 下。

對於擴充功能，那些僅用於API文檔且大多數終端用戶看不到的訊息應該放在單獨的文件中，其是運用針對擁有多個文件的正常機制。 請參閱關於新增訊息的本地化文檔。

命名

API模組的說明訊息是使用「模組路徑」來劃分命名空間，「模組路徑」是用於action=help的「modules」參數的字串。 對於那些要被添加到$wgAPIModules的模組，這將與該陣列中所使用的鍵相同；而對於被添加到$wgAPIPropModules、$wgAPIListModules、或$wgAPIMetaModules的模組，它將會是有加上前綴“query+”的鍵。

  • 先前由 getDescription() 方法所傳回的描述訊息已拆分為兩個部份：一個apihelp-$path-summary的訊息，其中包含模組的一行摘要；以及另一個apihelp-$path-extended-description的訊息，其中包含任何其他模組級文件。 這些方法都可以透過相應的方法進行覆蓋，但會需要這種情況的很少見。
    • 1.30 版本之前，使用的訊息是 apihelp-$path-description 。 雖然可以透過實作 getDescriptionMessage() 方法來覆蓋此限制，但會需要這種情況的很少見。
  • 先前由 $getParamDescription() 方法所傳回的參數訊息，現在是 apihelp-$path-param-$name（其中 $name 是 getAllowedParams() 中的鍵）。 可以透過在從 getAllowedParams() 傳回的資料結構中為 ApiBase::PARAM_HELP_MSG 設定值來覆寫此設定。
    • 某些參數其帶有類似於「當有更多結果可用時，請使用此選項繼續」的描述時，應使用 api-help-param-continue，而不是重新定義一個重複的訊息。
    • 排序參數取值為「newer」和「older」（以及相關的「start」和「end」參數）時，應使用api-help-param-direction，而不是重新定義一個重複的訊息。
    • 透過實現needsToken()得以使用CSRF令牌的模組不需要記錄token參數；ApiBase會自動處理此參數。
    • getAllowedParams() 中還有幾個其他常數可供使用；詳情請參閱ApiBase。
  • 某些參數其帶有一個ApiBase::PARAM_TYPE的陣列時，可以使用ApiBase::PARAM_HELP_MSG_PER_VALUE來指定哪一個值是被單獨記錄的。 這些訊息預設是 apihelp-$path-paramvalue-$name-$value。 如果訊息是按照預設值命名的，則無需將訊息對應到 ApiBase::PARAM_HELP_MSG_PER_VALUE 陣列中的值（它仍然必須存在、但可以留空）。
  • 所有範例都必須附有描述性的文字。 訊息名稱應遵循以下格式：apihelp-$path-example-$arbitrarySuffix。

消息文档

當要記錄 qqq.json 中的消息時，請使用以下模板：


消息格式

所有消息都應以句號結尾、且是語法正確的句子。 有關傳遞給訊息的預設參數，請參閱#消息文檔中連結的模板。

請在訊息中使用語義維基文字標記：

  • ‎<var>用於參數的鍵的提及、以及引用的變數(例如$wgMiserMode)的提及。
  • ‎<kbd>用於參數的可能值、參數及其值的提及（包括對其他模組的引用）、以及範例文件中輸入值的提及。
  • ‎‎<samp>用於在API輸出的鍵或值的提及。
  • ‎‎<code>用於其他任何電腦程式碼，例如「max-age檔頭」或「‎<head>頁面」。
  • 在使用語意標記時，不需要額外的引號。

如果需要引用其他API模組，使用管道符傳遞某個連結給 Special:ApiHelp，格式化程式就會執行正確的操作。 例如，文檔中會以“[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]”來表示各種不同的token參數。 如果 Special:ApiHelp 連結位於同一個頁面上，則它可以正確地將其呈現為頁面內錨定的連結（範例）。 同樣，對MediaWiki的組態變數（例如 $wgMiserMode）的引用應該連結到mediawiki.org上的文檔。

範例中引用的頁面通常不應添加鏈接，因為這些鏈接不太可能在許多維基上存在。

错误与警告

錯誤可以透過呼叫$this->dieWithError( $messageObjectOrKey );來引發、訊息可以以常用的方式進行本地化。 依樣畫葫蘆，警告也可以透過$this->addWarning( $messageObjectOrKey );來比照辦理。 详情请见API:Errors and warnings。

習慣上，API錯誤訊息會讓訊息鍵以apierror-開頭、警告訊息會讓訊息鍵以apiwarn-開頭。 您可以在訊息文檔中使用 {{doc-apierror}}。

在API响应中的文本

ApiBase本身、以及所有 API 模組，也是上下文的來源。 一般情況下，應使用 $this->msg() 存取訊息，並且在需要 IContextSource 時，一般應傳遞 API 模組本身。

不應因為客戶端可能覺得有用就隨意將訊息包含在輸出中。

在translatewiki上改进本地化

您可以像處理其他核心 MediaWiki 訊息一樣，在 translatewiki.net 上新增和改進API的訊息翻譯。 相關訊息群組包括有

Category:MediaWiki action API/zh Category:Pages using deprecated NoteTA template