API:Localisation/ja

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



メッセージ ファイル
MediaWiki コアの地域化メッセージは 配下にあります.

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



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


 * 以前は[//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a49b8857e40e254e0af27fd281f3a2230 getDescription] 方式で返された説明文メッセージは、2分類されました. メッセージは1行でモジュールを要約したもの、 にはモジュールレベルの説明文があります. これらは対応するモジュールで上書きされる場合がありますが、それが必要な確率はとても低いです.
 * 1.30以前は、 メッセージを使用. これは[//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#aa0c499873fba5c934b98aae65e61a33d getDescriptionMessage]方式を適用すると上書きされるものの、それが必要な確率はとても低いです.
 * 以前は[//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a1d9406dc4a7b6e5b69554c492ee464f6 getParamDescription]方式で返されたパラメータ説明メッセージは、 になります (  は[//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]に由来するキー. ) これは[//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]から返ったデータ構造値を に設定すると上書きされます.
 * 「その他の結果がある場合はこれを使って継続します」などの説明文を伴うパラメータは、重複するメッセージを表示せず、必ず api-help-param-continue を使用します.
 * 取る値が「より新しい」か「より古い」かパラメータを分類するには、 (関連する "start" と "end" パラメータあり) 重複するメッセージを表示せず、必ず api-help-param-direction を使用します.
 * を使って CSRF トークンを使用するモジュールには、 token パラメータの説明は不要です. これは ApiBase により自動処理されます.
 * [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]ではいくつかの追加の定数が使用可能です. 詳細は ApiBase を参照.
 * 列のあるパラメータは  を使って特定でき、各値は個別に説明されます. これらのメッセージは既定で となります. メッセージの命名が既定どおりの場合、メッセージと値の 列における対応付けは不要です(存在は必要だが空白でも可能. )
 * サンプル文にはすべて説明文をつけます. メッセージ名は に準じる必要があります.



メッセージの説明文
内でメッセージの説明文を記述する際は、以下のテンプレートを使用してください:


 * doc-apihelp-summary
 * doc-apihelp-description
 * doc-apihelp-extended-description
 * doc-apihelp-param
 * doc-apihelp-paramvalue
 * doc-apihelp-paraminfo
 * doc-apihelp-example



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

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


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

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

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



エラーと警告
エラーは を呼び出すと警告され、メッセージは通常の方法で地域化できます. また のある警告文も同様です. 詳細は を参照してください.

慣習上、メッセージキーの先頭はAPI エラーメッセージが 、警告文は でそれぞれ始まります. You can use doc-apierror in the message documentation.



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

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



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


 * MediaWiki 操作 API
 * API 機能の使用法



関連項目

 * – Draft document from 2014 with information for converting old API modules to the current system.