API:地域化

This page is a translated version of the page API:Localisation and the translation is 99% complete.

このページは MediaWiki 操作 API の説明文書の一部です。

MediaWiki バージョン:

≧ 1.25

Gerrit change 160798

このページは MediaWiki 操作 API (api.php) の地域化に固有のものごとを記述します。 MediaWiki 地域化に関する一般的なコメントは地域化を参照してください。

メッセージファイル

MediaWiki コアの地域化メッセージは includes/api/i18n 配下にあります。

拡張機能については、API 説明文書のみで使用されていて多くの利用者が目にすることがないメッセージは、複数のファイルに格納する通常のメカニズムを使用して、別のファイルに格納されているはずです。 See the localisation documentation about adding new messages.

ヘルプメッセージ

命名

API モジュール用のヘルプメッセージは「モジュールパス」つまりaction=helpの「モジュール」パラメータに用いる文字列を付けた名前空間に配します。モジュールを$wgAPIModules に追加した場合はその列に用いたキーと同一になり、追加先が$wgAPIPropModules 、$wgAPIListModules 、$wgAPIMetaModules の場合は接頭辞「query+」を付けたキーを当てます。

以前はgetDescription() 方式で返された説明文メッセージは、2分類されました。apihelp-$path-summaryメッセージは1行でモジュールを要約したもの、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 を使用します。
- 取る値が「より新しい」か「より古い」かパラメータを分類するには、 (関連する "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 内でメッセージの説明文を記述する際は、以下のテンプレートを使用してください:

{{doc-apihelp-summary|モジュールパス}}
{{doc-apihelp-description|モジュールパス}}
{{doc-apihelp-extended-description|モジュールパス}}
{{doc-apihelp-param|モジュールパス|パラメーター名}}
{{doc-apihelp-paramvalue|モジュールパス|パラメーター名|パラメーター値}}
{{doc-apihelp-paraminfo|モジュールパス|パラメータ情報のタグ名}}
{{doc-apihelp-example|モジュールパス}}

メッセージの整形

すべてのメッセージは、ピリオドで終わるようにすべきで、文法的な意味で「文」になるようにすべきです。既定でメッセージに渡されるパラメーターについては、#メッセージの説明文からリンクされているテンプレートを参照してください。

メッセージ内ではセマンティックなウィキテキストを使用します。

‎<var> でパラメータキーを述べ、$wgMiserModeなど変数を参照。
‎<kbd> でパラメータに使える変数、パラメータに当てる数値 (他のモジュール参照を含む) ならびにサンプル文中の入力値を示す。
‎<samp> は API 出力内のキーもしくは値を示す。
‎<code> はその他のコンピュータ用コードで、たとえば「max-age 見出し」あるいは「ページ ‎<head>」と示す。
セマンティックなマークアップ記述では、引用符の追加は不要。

他の API モジュールを参照する必要があるときには、リンクとSpecial:ApiHelpをパイプ記号で結ぶと、ヘルプフォーマット機能が正しい処理をします。たとえばさまざまな token パラメータの説明文書には「[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]」を使います。 Special:ApiHelp リンクにより、同じヘルプページ上にある場合はページ内のアンカー付きリンクとして正常にレンダリングが実行されます (サンプル。) 同様に、 $wgMiserMode などMediaWiki 設定変数を参照するには、必ず mediawiki.org にある説明文書にリンクさせます。

サンプルで参照したページは一般にリンクしないでください。多くのウィキではそのリンクを再現できないからです。

エラーと警告

エラーは$this->dieWithError( $messageObjectOrKey );を呼び出すと警告され、メッセージは通常の方法で地域化できます。また$this->addWarning( $messageObjectOrKey );のある警告文も同様です。詳細は API:エラーと警告を参照してください。

慣習上、メッセージキーの先頭はAPI エラーメッセージがapierror-、警告文はapiwarn-でそれぞれ始まります。メッセージの説明文では {{doc-apierror}} を使用できます。

API レスポンス内のテキスト

ApiBaseおよびすべての API モジュールはそれ自体がコンテキストのソースでもあります。一般に$this->msg()を使ってメッセージにアクセスする必要があり、API モジュール自体はIContextSourceが必要な場面で渡されます。

クライアントがそれを有用だと思うかもしれませんが、メッセージを任意に出力に含めるべきではありません。

translatewiki で地域化を改善

APIヘルプメッセージの翻訳は translatewiki.netで追加や改善ができ、その他のMediaWikiコアのメッセージとやり方は同じです。関連するメッセージ群には次のものを含みます。

メッセージ ファイル

ヘルプ メッセージ

命名