Jump to content

Help:システムメッセージ

From mediawiki.org
This page is a translated version of the page Help:System message and the translation is 85% complete.
Languages:
PD 注意: このページを編集すると、編集内容が CC0 のもとで公開されることに同意したと見なされます。詳細はパブリック・ドメインのヘルプ ページを参照してください。 PD
国際化の説明文書
Special:Upload のフォームの解説。ラベルはそれぞれのシステムメッセージを示す。

システムメッセージは平文やウィキテキスト、CSS、JavaScript のスニペットで、MediaWikiの振る舞いや、それぞれの言語とロケール (英語版) に合わせて外見をカスタマイズするために使用されます。 MediaWiki は利用者から見えるインターフェイスの要素すべてにメッセージを使っており、コアと拡張機能の両方で MediaWiki UI の国際化と地域化を可能にしています。 MediaWiki で使用されているメッセージはすべてメッセージ ファイル内で定義されています。

ウィキ上でのメッセージのオーバーライド

ウィキ上でメッセージを編集することでメッセージの既定値を上書きできます。 各メッセージには、MediaWiki 名前空間内に対応するウィキページがあり、そのページ名はメッセージ キーになっています。 例えば、「aboutsite」メッセージはMediaWiki:aboutsiteに格納されています。 既定では、「editinterface」権限を持っていない利用者は、この名前空間のページを編集できません。 すべてのメッセージ ページの一覧は、Special:AllMessages にあります。 インターフェイス メッセージの編集は簡単で、通常のウィキページの編集と同様ですが、editinterface 権限を持つ利用者のみに編集が制限されています。この権限は既定では、管理者 (およびインターフェース管理者) に割り当てられています。

古い Special:AllMessages の行の例。

Special:AllMessages の表には 2 つの列があります: リンクされたインターフェイス名とメッセージ文です。 メッセージ文は上下に 2 分割されていて、上に既定のメッセージ文、下にカスタマイズされたメッセージ文を表示します。 カスタムメッセージ文が存在しない場合、既定のメッセージ文のみが表示されます。 メッセージをカスタマイズするには、左の列の上にあるリンクをクリックします (メッセージ名)。 既定のメッセージ文が使用されている場合、編集ページが空であるためこのリンクは赤く表示されます。

左カラムのセルにある下側のリンクはそのメッセージのための議論ページになります。

ウィキ上でメッセージを上書きすることが推奨されるのは、以下の場合のみです:

  • メッセージに重大な誤りがあり、できるだけ早く修正する必要がある場合。 この場合、英語であればソース コード内の誤りを修正し、英語以外であれば translatewiki 上の翻訳を修正することも推奨されます。 修正が展開された際には、ローカル カスタマイズを含むページを削除する必要があります。
  • ローカル ウィキが異なる用語を使用している場合。 例えば、多くのメッセージでは「ページ」(page) という言葉が使われていますが、英語版ウィキペディアでは「記事」(article) と表現されることがよくあります。
  • ローカル メッセージがガジェットやテンプレートなどに特有の機能を追加しようとしている場合。 (このような場合でも、翻訳元メッセージを変更するか、この機能を拡張機能内に組み込むことを検討することをお勧めします。これにより、他のウィキも手動でカスタマイズをコピーすることなく、便利に利用できるようになります。)

メッセージとその解説文を見つける

各メッセージが MediaWiki でどのように使用されているか、利用できる変数、使用されているパラメーター、制限などは、仮想言語 qqq 内の完全な説明文ファイルで、メッセージ説明文のガイドラインに従って説明してあります。 一部のインターフェイス メッセージの長い説明ページについては、より古い カテゴリ:インターフェイス メッセージ 内にある場合があります。

translatewiki.net のウィキ ベースでは、qqq はメッセージの利用者向け解説文を保持するページです (すべての読者に同じように表示するため英語で記述)。

/en, /zu, /fr, ..., /qqq が記事の下位ページであり直接閲覧できるのと同様です。

この観点から、qqq は、リクエストのパラメーター language= では言語とみなされます。
MediaWiki バージョン:
≧ 1.18

MediaWiki 1.18 以降では、擬似言語コード qqx を使ってウィキ内のメッセージ・キーを検索できます。通常は URL の文字列の後に ?uselang=qqx を、もしくは ? 文字を含む URL であれば&uselang=qqx を足します（例）。 するとすべてのメッセージはメッセージ キーに置換され、どのメッセージが該当するか識別しやすくなります。 常にコンテンツの表示言語で表示させるメッセージは qqx を使わずに表示されます。

特別ページ「個人設定」 のようにタブに分かれたページの場合、uselang パラメーター（例：Special:Preferences?uselang=qqx#mw-prefsection-rendering）の後にタブを追加する必要があります。

MediaWiki バージョン:
≧ 1.38
Gerrit change 765385

MediaWiki 1.38 未満では、フォールバック メッセージ キーが表示されず、特にページ ナビゲーション タブなど、一部のメッセージの出典を特定することが困難でした。MediaWiki 1.38 以降、フォールバック メッセージ キーはスラッシュ (/) で区切られて表示されます。

MediaWiki バージョン:
≧ 1.43
Gerrit change 1025837

MediaWiki 1.43 未満では、(MessageCacheFetchOverrides などのフックを使用して) オーバーライドされたメッセージ キーも表示されず、拡張機能によってオーバーライドされたメッセージ (例: WikimediaMessages ) の出典を特定することが困難でした。MediaWiki 1.43 以降、オーバーライドされたメッセージ キーは等号 (=) の後に表示されます。

地域化ファイルの書式

MediaWiki で使用されているメッセージはすべて「メッセージ ファイル」内で定義されています。

MediaWiki のメッセージ ファイルには、JSON と PHP の 2 種類があります。 2014年4月時点で、コア MediaWiki と保守されている拡張機能のほとんどが JSON 形式に移行されました。 新規の開発ではすべて JSON を使うべきです。 JSON への移行の詳細は、Requests for comment/Localisation format を参照してください。

JSON

2013年後半から、メッセージの新しいファイル形式「JSON」が導入されました。 これは、一般的な汎用データ保存形式として親しまれている、プレーンな JSON です。 その中のすべてのキーがメッセージ キーであり、値がメッセージ テキストです。 また、特殊な @metadata キーは、翻訳の作者などの翻訳についての情報を保存するために使用されます。

JSON を使用すると、地域化ファイルが実行できなくなるため、より安全性が高くなります。 また、プロジェクト Milkshake の一部として開発された JavaScript ライブラリである jquery.i18n と互換性があり、MediaWiki のようなフロントエンドの地域化機能を提供し、ビジュアルエディターやユニバーサル言語選択など、MediaWiki にあまり依存したくないいくつかの拡張機能が使用します。

国際化・地域化ツール一式が「Project Milkshake」と呼ばれていたことから、この形式を「バナナ」と呼ぶ人もいます。

ファイルの場所

MediaWiki コアでは、地域化ファイルは languages/i18n ディレクトリに配置されます。 MediaWiki 拡張機能は通常、それらを i18n/ 下位ディレクトリに配置します。 プロジェクト内に大量のメッセージが存在する場合、保守性を高めるためにこれらを 2 つ以上のトピカルな下位ディレクトリに分割することが望ましい場合があります。 MediaWiki の文脈では、$wgMessagesDirs 構成キーがこれらの下位ディレクトリを列挙するために使用されます。 以下は、MediaWiki 用 VisualEditor 拡張機能の例です: 

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

新規のメッセージは英語版のメッセージ用ファイル "en" と en.json に追加、メッセージ解説文に説明を書き込んで、仮の言語コード（pseudo-language code）"qqq" – qqq.json を当てます。 関連項目：新規メッセージの追加。

メタデータ

現状、ファイル類では以下のメタデータ・フィールドを採用しています:

authors
メッセージ執筆者の JSON 名簿。 英語 (en) ならびにメッセージ解説文書 (qqq) では、メッセージ・ファイルを編集した時にこれらを手動で追加します。 他のすべての言語では、メッセージ ファイルが translatewiki.net からエクスポートされるとき、これを自動的に挿入します。 メッセージ解説文を編集する場合は translatewiki.net で実施し、qqq.json ファイルにも解説文書の編集機能が自動で追加します。
message-documentation
これは偽言語コードで、メッセージ文書の保存に使います。 メディアウィキではこれは常にqqq。 （複数の拡張機能に出現するものの、実際に何らの処理もしません。義務でもありません。）

規約

改行などの特殊文字はエスケープされます ("\n")。

異なる文字体系の文字を表す Unicode 文字は、文字コードではなく実際の文字として保存されます。これは、これらのファイルが人間により閲覧されることがあり、またそのほうがファイル サイズが小さくなるためです ("\u8ABC" ではなく "誼")。 いずれにせよ、開発者が英語以外の言語でメッセージを編集する理由はほとんどありません。これらのメッセージは通常、translatewiki.net を通じて編集されるからです。

HTML コードもエスケープされません。つまり、"\u003cstrong\u003eWarning\u003c/strong\u003e" ではなく "<strong>Warning</strong>" です。

JSON ファイルはタブでインデントされています。

PHP

この節で解説するものは2014年に廃止された、メッセージの地域化に用いる MessagesXx.php ファイルの使い方を述べています。 ただしファイル類は今でも他の言語特化型の設定 に採用されています。

過去の地域化ファイル書式は PHP でした。 これは、すべてのメッセージを含む PHP 配列です。 MediaWiki のコアでは、それぞれの言語が MediaWiki ソースコード内の languages/message ディレクトリに専用のファイルとして存在します。 拡張機能では、すべての言語とメッセージの文書化 (qqq) が同じファイル (通常は拡張機能のメイン ディレクトリにある ExtensionName.i18n.php) に含まれます。

システム メッセージを PHP から JSON に移行するには、generateJsonI18n.php スクリプトを使用してください。 このスクリプトはメッセージを JSON ファイルに移動し、PHP ファイルの内容を JSON ファイルを参照する中継コードに置き換えます。 

MediaWiki 1.19 では、このボイラープレート・コードは逆の互換性用に欠かせません。

MediaWiki 1.19 互換性を必須としない新しい拡張機能では、採用されません。

メッセージの使用

MediaWiki では、コード内のキーによって参照されるメッセージの、中央管理 リポジトリ方式を使用しています。 この方式は、例えば gettext などが採用している、ソースファイルから翻訳可能文字列を抽出するだけの方式とは異なります。 キー ベースのシステムでは、翻訳元のテキストの改善や、メッセージの変更の追跡がより容易になります。 もちろん使用されたメッセージの一覧やそれらのキーに対応する翻訳原文の一覧が陳腐化するという欠点はつきものです。 実用上は大きな問題ではなく、特筆するべき唯一の問題点とはどこにも使われなくなった余計なメッセージでも翻訳対象として残る点です。

Making messages findable

メッセージキーの管理と検索の利便性を高めるには、grep も含め、常に記述を完結させなおかつ動的な定義を避けることです。 コードの構造を改善すると思われる場合は、メッセージ・キーの一部を連結できますが — これは確実に複数の可能性がある場合にのみ実施することと[1]、その直後などに必ずコメントをに記載し、連結を反映したら得られそうなキーのリストも添えてください。 例： 

// ここで使用できるメッセージ例:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

動的識別子のコーディング規約も参照してください。

メッセージを読み込んで JavaScript コードで使う

JavaScript でメッセージを用いるには、属性が "messages" になるようにご利用のResourceLoader モジュールの定義内に一覧として加えてください。

Message usage functions

PHP および JavaScript 内でのメッセージ関数の使用方法の詳細は、Manual:メッセージAPI を参照してください。 この解説ページは重要で、メッセージを用いるコードを書く前に必ず通読しなければなりません。

メッセージのソース

コードがシステムメッセージを読みに行く元は以下の通りです。

  • MediaWiki 名前空間。 これはウィキ類で基本のメッセージを使いたくない、もしくは不適切な場合、すべてのメッセージを適応つまり上書きさせます。
    • MediaWiki:Message-key が既定のメッセージで、
    • 利用者がウィキの規定以外の言語を選択済みの場合に使うメッセージは MediaWiki:Message-key/language-code です。
  • メッセージファイル類のうち:
    • MediaWiki のコア自体と現状で管理されている拡張機能の大半は言語と1対1対応のファイルを zyx.json と呼び、その言語の言語コードは zyx です。
    • 一部の古い拡張機能では、すべての言語のすべてのメッセージをまとめて格納する、拡張機能名.i18n.php という名前のファイルが使われています。
    • 多くのウィキメディア財団のウィキ群では、WikimediaMessages 拡張機能から一部のメッセージにアクセスしており、これによってすべての MediaWiki インストールに強制することなく、WMF ウィキ群全体でメッセージの標準化が可能になります。
    • ごく一部の拡張機能では、別の手法が使われています。

キャッシュ

システム メッセージは、MediaWiki のより重要な構成要素のひとつです。主に、すべてのウェブリクエストで使用されるためです。 PHP のメッセージ ファイルは、数千のメッセージ キーと値を格納しているため、大きなサイズになります。 このファイルの読み込み（利用者の言語がコンテンツ言語と異なるなら複数ファイル）はメモリとパフォーマンスのコストが高くなります。 パフォーマンスに与えるこの影響を減少させるため、大胆に層序を欠けたキャッシュシステムを採用しています。

MediaWiki にはキャッシュのメカニズムがたくさん組み込んであり、コードの理解をいくぶん難しくしています。 1.16 以降、キャッシュの新システムを導入して、メッセージは cdb fファイルもしくはデータベースでキャッシュしています。 カスタム・メッセージは、設定に応じて filesystem と memcached（もしくは代替） でキャッシュします。

関連の設定は以下の表にまとめました。

キャッシュ格納領域の場所 $wgLocalisationCacheConf
'store' => 'db'
 		 'store' => 'detect'
(既定)		 'store' => 'files'
 		 'store' => 'array'
(MW ≥ 1.26以降の試験版)
$wgCacheDirectory = false
(既定) 		l10n cache table l10n cache table エラー (パスが未定義) エラー (パスが未定義)
= path l10n cache table ローカル ファイルシステム (CDB) ローカル ファイルシステム (CDB) ローカル ファイルシステム (PHP 配列)
MediaWiki バージョン:
1.27.0 – 1.27.2
Gerrit #Id3e2d2

MediaWiki 1.27.0 と 1.27.1 では自動検出がファイルのバックエンドを優先するように変更しました。 'store' => 'detect'（既定）の場合、ファイルのバックエンドは$wgCacheDirectory からパスを得て使います。 この値が未定の場合（それが既定）、使用する仮ディレクトリはOS（オペレーティングシステム）が決定します。 仮ディレクトリを検出しない場合は、データベースのバックエンドをフォールバックとして採用します。 共有ホスト上のファイル衝突とセキュリティ問題（T127127 と T161453）が原因で、1.27.2 と 1.28.0 から元に戻りました。

関数名を遡って探す

キャッシュの階層を視覚的により分かりやすく示すために、メッセージ取得時に呼び出されるメソッドの関数バックトレースを示します。 それぞれのレイヤの説明は、以下の各節を参照してください。

  • Message::fetchMessage()
  • MessageCache::get()
  • Language::getMessage()
  • LocalisationCache::getSubitem()
  • LCStore::get()

MessageCache

メッセージのキャッシュにはMessageCacheクラスが最上位のレイヤーです。 Message クラスから呼び出し、特定のメッセージの最終的な未加工の内容を返します。 このレイヤが処理する論理は以下のとおり：

  • データベースに問い合わせてメッセージのオーバーライドを確認
  • memcached 、または $wgMessageCacheType に設定されているものに上書きされたメッセージをキャッシュする。
  • 言語フォールバック順序のリマインダを解決

箇条書きの最後の項が肝心です。 言語の連鎖により、ウィキメディアでは元のメッセージを求めていない場合、他の言語にフォールバックできます。 次の節に述べるとおり、言語フォールバックの解決のほとんどは、より低いレベルで行われます。 しかしながら、上書きしたメッセージはMessageCache レイヤーに限定してデータベースと照合します。 そのため、データベース由来のオーバーライド済みメッセージはここでフォールバックチェーンに統合。 データベースを利用しない場合は、このレイヤ全体を無効にしてください。

LocalisationCache

LocalisationCache.php を参照

LCStore

LCStore クラスとは実際にメッセージをキャッシュして取得する LocalisationCache a にとって、単なるバックエンド実装です。 BagOStuff クラス同様に、MediaWikiで一般的なキャッシュに使うものであり、複数の異なるキャッシュタイプがあります（設定は$wgLocalisationCacheConf を採用）：

  • db （既定）- メッセージをデータベースにキャッシュ
  • file （$wgCacheDirectory を設定済みの場合の既定）- CDB を採用してローカルのファイルにキャッシュ
  • accel - データ保存にAPCまたは別のオペコードキャッシュを使用

file オプションはウィキメディア財団が使用し、特に PHP バージョン5.5以降と互換性がない APC キャッシュと比べると、信頼性も高くデータベースに遡及しない分高速だから推奨。

新しいメッセージの追加

メッセージキーを選ぶ

関連項目: Manual:コーディング規約

メッセージキーはグローバルに1対1対応の必要があります。 これには、MediaWiki のコア部分とすべての拡張機能および外装が含まれます。

メッセージの名前はアルファベットの小文字、数字、ダッシュのみで記述します。 その他の文字は実用性が低いかまったく役に立たないかのどちらかです。 MediaWiki の慣例では、先頭文字は大文字小文字を区別せず、その他の文字は大文字小文字を区別します。

命名は、グローバルまたはローカルの慣習に従ってください。 拡張機能の場合は標準の接頭辞を使用します。できれば拡張機能名を小文字にして、ハイフン (-) を続けます。 例外は以下の通りです:

APIによって使用されるメッセージ
これらは apihelp-、apiwarn-、apierror- のいずれかで始まる必要があります。 この接頭辞の後に拡張機能用の接頭辞を付けます。 (これらのお知らせは別ファイルに置くべきで、通常は includes/i18/api に含めます。)
ログ関連のメッセージ
これらはlogentry-、log-name-、log-descriptionで始めてください。
利用者権限
Special:ListGroupRights に表示される権利名の手掛かりとなるよう1文字目は必ず right- にします。 文末を示す動作は「あなたには「$2」を行う権限がありません。理由は以下の通りです:」と呼び、1文字目は必ず action- にします。
版タグ
版タグの1文字目は必ずtag-。
特別ページの名前
特別ページの名前は1文字目が必ずspecial-。
拡張機能の説明
拡張機能の説明は必ず前半が拡張機能の名称、語尾は -desc。

Special:Versionでは表内に示し、拡張機能が何をするのか簡明に述べてください。

ジェンダー

英語のメッセージでは、利用者の性別によって変わる異なる単語が必要になることはほとんどありません。 英語では、第三者代名詞 (「he」や「she」) で性別の違いを区別する必要がありますが、驚くほどメッセージ内ではこれらは稀です。 これが必要なら {{GENDER:$1|he|she|they}} を使用してください。

しかし、多くの他の言語では、三人称代名詞に限らず、他の代名詞や、さまざまな時制の動詞 (例:「作成した」、「削除した」)、名詞 (例:「メンター」、「管理者」)、形容詞 (例:「新しい」) などにおいても、利用者の性別に応じて異なる語を用いる必要があります。 したがって、英語のメッセージでは、たとえ英単語しかなくても、GENDER を使用することがよく役立ちます。 これにより、翻訳者にはメッセージ内で GENDER を使用できることが示唆されます。 これにより、省略可能な利用者名パラメーターが欠けている場合に (特に記録項目メッセージでよく発生する)、translatewiki で表示されるパラメーター不足の警告を回避することにもなります。

メッセージを作成するときにその他に注意すること

  1. メッセージに（解析、{{の置換、HTMLのエスケープなど）適切な処理を採用しているかどうか確認してください。
  2. メッセージがコア部分に属する場合、通常は languages/i18n/en.json に追加する必要があります。ただし、インストーラー、EXIF タグ、ApiHelp、個人設定など、特定のコンポーネントにはそれぞれ専用のメッセージ ファイルがあります。
  3. メッセージが拡張機能に含まれる場合は、適切なサブディレクトリにあるi18n/en.jsonファイルもしくはen.jsonファイルに追加します。 具体的には、エンドユーザーのほとんどは見ないままで開発者しか見ない API メッセージ類は通常、別ファイルにまとめ、一例として i18n/api/en.json があります。 特定の拡張機能にメッセージが大量にある場合、 i18nの配下にサブディレクトリを作ることもできます（複数可）。 既定のi18n/を含め、メッセージ用ディレクトリは必ず全件をextension.jsonのMessagesDirs節もしくは$wgMessagesDirs 変数にリストします。
  4. ここでいったん手を止めて、メッセージの言い回しを吟味してみましょう。 不明確な点はありませんか？ 何か読み違いそうな点は？ 頼めるなら、他の開発者あるいはローカライズ担当者に感想を尋ねましょう。 国際化のヒントに従います。
  5. 説明文を同じディレクトリ内の$ に追加
  6. やみくもにアルファベット順に並べるのはやめてください。 メッセージは必ず皆さんのプロジェクトの機能順にファイル内に置きます。 同じ拡張機能由来のメッセージは連続するように配置。 こうすると翻訳者は集中力をキープして効率よく一貫性のある作業ができます。
  7. メッセージまたはその説明文書 (qqq) が、同じ JSON ファイル内の別のメッセージを参照している場合は、参照元のメッセージを参照先のメッセージの後に配置するようにしてください。これにより翻訳者は、参照元のメッセージを翻訳する前に参照先のメッセージを翻訳できるようになります。 一例として複数のメッセージが連動する場合など、その方法は毎度は採用できませんが、可能な場合はできる限りその方法で処理してください。 （典拠（referring）の記述は通常、メッセージ内にマジックワードの {{int:key}} があるなら対応したり、あるいは qqq 解説文書に含まれる {{msg-mw}} テンプレートを使ったりします。具体的な操作はメッセージ解説文書を参照してください）
  8. もっとも基本的で頻繁に使うメッセージ類は当該のファイルの先頭に配置し、めったに使わないし技術的に高度なものは末尾に寄せます。

翻訳するべきではないメッセージ

  1. 無視されたメッセージとは、英語のメッセージ・ファイル限定に置くするべきもの。 そのメッセージとは e.g.、"{{SITENAME}}"のメッセージのように、他のメッセージを示す、もしくは多言語共通であり、翻訳の対象から除外するものべきです。
  2. オプションのメッセージとは、訳出する言語で変更が発生する場合に限定。

このようなメッセージに付けるフラグとは：

既存のメッセージの除去

en.json と qqq.json から除去。 他の言語版はそのままにしておきます。 translatewiki.net 経由の更新によってそれらは自動処理されるはずです。

さらに、そのメッセージがたとえば選択制もしくは無視される、あるいは多用されるメッセージ群一覧など、 translatewiki 設定内に現れないかどうか確認（簡略な git grep で対応可）。 必要に応じて上記のリストから除去。

既存のメッセージの変更

  1. メッセージの解説文の更新を検討してください。
  2. 旧版の訳文が新しい意味に適合しない場合は、メッセージのキー変更を検討。 これにはメッセージの扱い（パース、エスケープ、パラメータその他）の変更も含まれます。 技術的に変更せずメッセージの言い回しを改訂するなら、通常はキー変更の理由になりません。 translatewiki.netでは訳文は更新が必要とマークされ、翻訳者の目印になります。 メッセージのキー変更には、翻訳担当の i18n チームとの話し合い、あるいはサポート申請は不要です。 しかしながら、特殊な状況もしくは疑問に遭遇した場合には、translatewiki.net のサポートページもしくは #translatewiki 接続 で質問しましょう。
  3. translatewiki.net のサポートを受ける拡張機能の場合は、キーおよび／もしくは英語の元メッセージと、付随するエントリを qqq.json で改変。 必要な場合、translatewiki.net チームが訳文更新の手順を引き受け、更新が必要とマークをつけたり、可能な場合はファイル整理やキー改名の処理をするはずです。 もしも 変更点が HTML タグなどに限定される場合も適合し、対象言語が話せなくても他言語でもそれらを変更可能です。 左記の処理のほとんどは translatewiki.net で実行しており、Git への到着にはまる1日ほどの遅延があります。

メッセージの説明文

メッセージの解説文には、偽言語コードの qqq があります。 それは個人的な利用に使う ISO 639 コードに含まれます。 そこでは各メッセージ単位の翻訳文は保持しませんが、各メッセージ単位に対応する 英語文は収集します：どこで使われるか伝え、翻訳方法のヒントを与えること、そのパラメータの列挙と記述をすること、関連メッセージへのリンク提示、その他。 translatewiki.net では編集者がメッセージを翻訳するときに、これらのヒントを表示します。

プログラマーは全てのメッセージを記録すべきです。 メッセージの解説文とは欠かすことのできないリソースであり – 単に翻訳者対象というよりも、モジュールのりに全員の役に立ちます。 ソフトウェアにメッセージが追加されるたびに、対応する qqq エントリも必ず追加する必要があります。説明文書が追加されるまで、これを行わない改訂は「V-1」とマークされます。

qqq ファイルの説明文書は、新しいメッセージを追加する場合や、既存の英語メッセージを説明文書変更が必要な形で変更する場合 (例えばパラメーターの追加/除去) に限り、直接編集して構いません。 その他の事例では、説明文の編集は通常、translatewiki で行う必要があります。 どの解説文の文字列もそれが翻訳であるなら、 https://translatewiki.net/wiki/MediaWiki:message-key/qqq で確認できます。 これらの編集はソースのリポジトリに訳文と共にエクスポートされます。

解説文書には次のような有意義な情報を書きこむことになっています。

  1. メッセージ処理（解析やエスケープの方法、平文）
  2. パラメータの種類とサンプル値。
  3. メッセージを採用している場所（ページ、ユーザインターフェース内の位置）。
  4. そのメッセージを置いた場所でどう使うか（ページ名、ボタンの文字その他）。
  5. このメッセージと共に使う他のメッセージ、またはこれが参照する他のどのメッセージとは。
  6. メッセージが文脈内で見られた場合には理解できるが、単独で表示された場合には理解できない内容 (翻訳時にはこちらの状況が該当) など。
  7. 適応するなら文法の説明を付与。 一例として、英語の「open」は動詞であり形容詞でもあります。 他の言語の単語は異なるので説明文がないとどう翻訳するか推測は不可能です。
  8. 形容詞がものごとを修飾するとき、「無効の」「開いてある」「ブロック中の」などはつねにその対象を示してください（disabled、open、blocked）。 In many languages adjectives must have the gender of the noun that they describe. It may also happen that different kinds of things need different adjectives.
  9. メッセージに特別な性質がある場合、例えばページ名である場合や、直接翻訳せず文化やプロジェクトに合わせて調整する必要がある場合など。
  10. Whether the message appears near other message, for example in a list or a menu. The wording or the grammatical features of the words should probably be similar to the messages nearby. さらに、リスト内の項目は場合により、リストの見出しときちんと呼応させるべきです。
  11. Parts of the message that must not be translated, such as generic namespace names, URLs or tags.
  12. Explanations of potentially unclear words, for example abbreviations, like "CTA", or specific jargon, like "template", "suppress" or "stub". (Note that it's best to avoid such words in the first place!)
  13. Screenshots are very helpful. Don't crop – an image of the full screen in which the message appears gives complete context and can be reused in several messages.

他のヒント:

  • Remember that very, very often translators translate the messages without actually using the software.
  • 一般論として、翻訳者にはそのモジュールもしくはその内包するメッセージ類に関する文脈の情報が全く示されません。
  • A rephrased message alone is useless in most circumstances.
  • Don't use designers' jargon like "hamburger", "nav", or "comps".
  • Consider writing a glossary of the technical terms that are used in your module. If you do it, link to it from the messages' documentation.
  • Message documentation is shown on translatewiki and parsed as wikitext. If you use mention wikitext or HTML tags that are supposed to be shown as is and not parsed, use ‎<nowiki>.

{{msg-mw|message key}}を利用すると他のメッセージにリンクが張れます。 メッセージの一部が他のメッセージに由来する場合 (これを避けられない場合)、または複数のメッセージが一緒に、もしくは同じ文脈で表示される場合は、この対応を行ってください。

解説文書に適用するように、translatewiki.net が提供する既定のテンプレートは次のとおり：

{{doc-action|[...]}}
for action- messages
{{doc-right|[...]}}
for right- messages
{{doc-group|[...]|[...]}}
for messages around user groups (group, member, page, js and css)
{{doc-accesskey|[...]}}
for accesskey- messages
{{doc-api*|[...]}}
API ヘルプと API エラー告知メッセージ用のテンプレート類
{{doc-api*|[...]}}
a set of templates for API help and API error messages
{{experimental}}
a template for marking messages that are likely to change in the near future (remember to remove it when the message stabilizes)
{{logentry}}
a template for marking log messages
{{optional}}
a template for marking optional messages, which shouldn't be translated to most languages, and which aren't shown to translators by default
{{ignored}}
a template for marking ignored messages, which must not be translated at all
{{doc-important}}
a template for emphasizing a paragraphs in the documentation.

この種のテンプレートは、Message Documentation Templates カテゴリにまとめてあります。 詳細は、テンプレートの解説ページを参照してください。

国際化のヒント

説明文書に加えて、翻訳者は開発者に対して、作業をより簡単かつ効率的にし、すべての言語で適切で質の高い地域化を可能にするためのいくつかのヒントを考慮するよう求めます。 Even if only adding or editing messages in English, one should be aware of the needs of all languages. それぞれのメッセージは 300 超の言語に対訳されるため、これは最善の方法で実施しなければなりません。 Correct implementation of these hints will very often help you write better messages in English, too.

Localisation#Help and contact info lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.

メッセージのパラメーターやスイッチを適切に使用する

That's a prerequisite of a correct wording for your messages.

メッセージの再利用を避ける

The translators discourage message re-use. まるで直感的と版するように見えても、コードの複写あるいは転写は悪い手法であっても、システム・メッセージではしばしば必要です。 英語では 2 つの概念を同じ単語で表現できても、すべての言語で同じ単語で表現できるとは限りません。 "OK" は適した例です：英語版では一般的なボタンのラベルに使いますが、言語版によってラベルはボタンを押すと実行する操作を示すようにしています。 もう一つの例は、ほとんどすべての形容詞です。「multiple」のような単語は、多くの言語で性によって変化するため、異なる複数の対象を表すために再利用できず、いくつかの別々のメッセージを作成する必要があります。

もしもよく似たメッセージを複数、追加しようとする場合は、メッセージに説明文をつけてそれぞれの文脈がどう異なるのか解説してください。 翻訳者の手間を増やすかもしれないなどは気にしないでください。 Translation memory helps a lot in these while keeping the flexibility to have different translations if needed.

「継ぎ接ぎ」メッセージの回避

Languages have varying word orders, and complex grammatical and syntactic rules. メッセージが複数の文の断片で構成されていて「文字列連鎖」（string concatenation）とも呼ばれる間接性がコード内にあり、翻訳者が直接にコントロールを許されない場合は、それらメッセージを技術者の符丁で「レゴ」（lego）もしくは「パッチワーク」（patchwork）と呼びます。事実上、「lego」メッセージを正確に翻訳することは不可能です。

Make every message a complete phrase. Several sentences can usually be combined much more easily into a text block, if needed. 複数の文字列を 1 つのメッセージにまとめたい場合は、パラメーターとして渡してください。翻訳者は翻訳時にそれらを自分の言語に合わせて正しい順序に並べられます。

互いに引用するメッセージ

メインのページ: Manual:Messages API#Referring to other messages

ルールの例外には相互に参照するメッセージが含まれます。「"{{int:name}}" という名前の欄に原作者名を記入してから、"{{int:proceed}}" をクリック」。 This makes the message consistent when a software developer or wiki operator alters the messages "name" or "proceed" later. int のトリックを使えないと、開発者もオペレータもどれか1件の修正の影響で、関連のどのメッセージも調整しなければならないか全件を把握する必要ができます。

自然言語でメッセージを書く

As much as possible, write messages in natural, human language. Try reading the message aloud and think: is this something that sounds like correct, grammatical English that humans speak? If it's complex, hard to pronounce, or in any way unnatural in English, it will be even harder for translators and for users in other languages.

Avoid punctuation that is too technical or bureaucratic or that can't be read aloud. Slash (/) should usually be replaced with "or". And/or should be replaced with "and" or "or". Sentences with comma splice should be split into shorter sentences.

特定のプロジェクトに特化した用語やテンプレートを使用しない

MediaWiki is used by very diverse people, within the Wikimedia movement and outside of it. Even though it was originally built for an encyclopedia, it is now used for various kinds of content. よって、一般的な語句を使ってください。 For example, avoid terms like "article", and use "page" instead, unless you are absolutely sure that the feature you are developing will only be used on a site where pages are called "articles". Don't use "village pump", which is the name of an English Wikipedia community page, and use a generic term, such as "community discussion page", instead.

特定のテンプレートが全てのウィキにあると思わないでください。 テンプレートはウィキに固有のものです。 This applies to both the source messages and to their translations. メッセージにテンプレートを使う場合も、その機能を導入するそれぞれの ウィキ単位で当該のテンプレートを作成して初めて、有効です。 メッセージではテンプレート類を使わないようにすることが最善の手法です。 どうしても使う必要がある場合は、そのことを必ずメッセージの説明文および拡張機能のインストール指示文に明確に書き残してください。

文章で時刻を日付から分離する

Some languages have to insert something between a date and a time which grammatically depends on other words in a sentence. Thus, they will not be able to use date/time combined. 他の人たちにはこの組み合わせが便利で、そういう場合、通常はパラメータ値を3件添えると最適で（日付／時刻、日付、時刻）、翻訳段階で最初の訳語のみ使うか、2番目と3番目のみ使うか 切り替えます。

メッセージで {{SITENAME}} を避ける

{{SITENAME}}にはいくつか欠点があります。 何でも（頭字語、単語、短い文、"etc. など）該当可能であり、言語によっては、出現のたびに{{GRAMMAR}} の適用が必要な場合もあります。 条件がどうであれ、ほとんどのウィキ言語では {{SITENAME}} を含むメッセージはどれも、そのコードをインストールするであろう新規ウィキの検証が必要です。 過半数の事例では、特定の言語に対応する一般的な GRAMMAR 設定がない場合、ウィキの運営者には PHP コードを追加または修正する責任があり、{{SITENAME}} に対応する {{GRAMMAR}} が作動するようにしてください。 これには熟達と深い理解のどちらか一方ではなく、両方が必須です。 「この wiki」のように一般的な参照法を使う方が実利的です。 これはローカルにインストールした場合にこれらメッセージに {{SITENAME}} を使って改変する妨げにはなりませんが、少なくとも改変は必須ではなく、メッセージの適正化はそのウィキが作動し利用が始まった後でも間に合います。

レイアウトの見た目や位置を説明に使わない

なにをどこに配置するかは外装によって左右されます。 右書き言語は左書きのそれと比べると、毎回ではなくても画面レイアウトがしばしば反転して表示されがちで、言語もしくはウィキによって全く反転しません。 携帯型デバイスやウィンドウが小さい場合、大画面なら横に並べて表示するブロックを縦に配置することがあります。 サイトや利用者が記述したJavaScript スクリプトやガジェット類は予測できない形で部分的に非表示にしたり対象物の位置を変えたりする能力があり、現実に実施しているため、実際のレイアウトを確実に理解する方法はありません。

配置の情報をコンテンツ言語に結びつけるのは誤りで、理由はユーザインタフェースの言語がページの内容の言語と一致するとは限らず、また状況によっては双方を混在させてレイアウトを保っている可能性もあるからです。 非視覚的なユーザーエージェントの場合、スクリーン読み上げソフトその他、補助デバイスには視覚的なレイアウトの概念すらありません。 そこで、大部分の場合は見た目の文字配列に頼るべきではありませんが、それでも意味論によるレイアウト用語は引き続き使用できます（「フォームの前のステップ」など）。

MediaWiki は、インタフェースのその時点の方向性に基づき、複数のメッセージやメッセージの断片を使い分ける表示方法に対応していません（T30997 を参照）。

ブラウザと MediaWiki は東アジア、北アジアの縦書き文字 [2] を対象にする次回のサポートでは、画面のレイアウトはさらに予測不能になり、レイアウト案は少なくとも8種類以上あります（上下左右のどこが起点で、その4点のどこが起点か）。

画面の色の参照の回避

文の要素のどれを何色でレンダーするか左右する条件はたくさんあり、外装のほかもJavaScript を記したのがサイトか利用者か、またアクセス性もしくは技術面の制限に合わせてローカルのユーザーエージェントが上書き処理するかなどがあります。 非視覚的なユーザーエージェントの場合、スクリーン読み上げソフトその他、補助デバイスには視覚的なレイアウトの概念すらありません。 よって、スクリーンの色には言及しないでください。 (You should also not rely on colour alone as a mechanism for informing the user of state, for the same reason.)

翻訳が不要なマークアップは回避する

HTML markup not requiring translation, such as enclosing ‎<div> tags, rulers above or below, and similar, should usually not be part of messages. It's an unnecessary burden on translators, and is often accidentally altered or skipped in the translation process. The translation interface has no syntax highlighting and limited validation, so mistakes are common.

Avoid complex wikitext markup as well. Wikitext is sometimes terser than writing the same thing in PHP, and it's tempting to write something like:

MediaWiki:Revreview-basic/en
This is the [[{{MediaWiki:Validationpage}}|stable version]], [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} checked] on <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} $3 pending {{PLURAL:$3|change|changes}}] {{PLURAL:$3|awaits|await}} review.

しかしながら、これでは翻訳者には扱いづらく、特に左書き言語の場合はメッセージ内の一部を英文のまま保持しようとすると、同じ行内で何度も書字方向が変わってしまいます。

MediaWiki:Revreview-basic/ar
هذه هي [[{{MediaWiki:Validationpage}}|النسخة المستقرة]]، [{{fullurl:{{#Special:Log}}|type=review&page={{FULLPAGENAMEE}}}} المفحوصة] في <i>$2</i>.
[{{fullurl:{{FULLPAGENAMEE}}|oldid=$1&diff=cur}} {{PLURAL:$3||تغيير واحد معلق|تغييران معلقان|$3 تغييرات معلقة|$3 تغييرا معلقا|$3 تغيير معلق}}] {{PLURAL:$3||ينتظر|ينتظران|تنتظر|ينتظر}} المراجعة.

リンクのターゲットを通す最善の方法はメッセージの変数にすることであり、マークアップは簡略な [$1 Label] や [[$1|Label]] などのみを使います。

Don't use the formatnum magic word within messages. Format the number parameters in the code that loads the message according to the instructions in Manual:メッセージAPI .

翻訳済みのメッセージは想定外の長さに達することが多い!

Skimming foreign language message files, you almost never find translated messages shorter than Chinese ones and rarely shorter than English ones. However, you will often find translations that are much longer than English ones.

特にフォーム類の場合、記入欄の直前では英語のメッセージは簡潔で短くなりがちです。 これはしばしば訳文から落とされています。 言語によっては英語にある専門用語が足りない場合があり、一部の概念を説明しようとすると複数の単語や完全な文が必要になることもあります。 For example, the brief English message "TSV file:" may have to be translated in a language as literally:

ここに記入する名称は、一連の行で構成したコンピュータデータの集合を表します。各行はそれぞれ一連の情報欄として構成され、各情報欄はフェンス（柵）で囲まれています。その柵は単一の記号で、まるでタイプライターのキャリッジを次の所定の位置へ動かすように機能します。では、実例です：_____（ありがとうございます）

This is, admittedly, an extreme example, but you get the trait. もしも、この文がフォーム内の特定の列に配置してあり単語単位で改行してある場合で、入力欄は次の列の高さ中央に配置してあると想定してみます。 :-(

異なるものや概念を示すために非常に近い、類似または同一の単語を使用するのを避ける

For example, pages may have older revisions (of a specific date, time, and edit), comprising past versions of said page. The words revision, and version can be used interchangeably. A problem arises, when versioned pages are revised, and the revision, i.e. the process of revising them, is being mentioned, too. This may not pose a serious problem when the two synonyms of "revision" have different translations. Do not rely on that, however. It is better to avoid the use of "revision" aka "version" altogether, then, so as to avoid it being misinterpreted.

Basic words may have unforeseen connotations, or not exist at all

There are some words that are hard to translate because of their very specific use in MediaWiki. Some may not be translated at all. 一例として、複数の言語には 「何かを使う人」という意味の「利用者」（user）に相当する単語はありません。 同様に、ケルン語（Kölsch）に翻訳すると英単語の namespace も apartment（名前空間も集合住宅）も訳語は同じです。 Also, in Kölsch, they say "corroborator and participant" in one word since any reference to "use" would too strongly imply "abuse". 用語「ウィキファーム」（wiki farm）とは、たった1種類の穀物の畑というと言語上に矛盾があって意味が通じないためなど、「ウィキだらけの馬小屋」（stable full of wikis）と解釈されます。

必要なときに ‎<code>、‎<var>、および ‎<kbd> タグを使用する

技術面のパラメータや値、キーボード入力に関しては、適切にマークアップするためHTML タグの ‎<code>、‎<var>、‎<kbd>などを使用。 そういうわけでこれらは印刷上、通常のテキストとは区別されます。 That clarifies their sense to readers, avoiding confusion, errors and mis-representations. Ensure that your message handler allows such markup.

記号、コロン、括弧などはメッセージの一部

Many symbols are localisable, too. Some scripts have other kinds of brackets than the Latin script has. コロンは、言語版によっては個別のラベルもしくは入力プロンプトに続けて使うと不適切です。 これらの記号をメッセージに書き込むと、英語中心主義に縛られない、より良い翻訳が可能になり、またコードの混乱も軽減します。

For example, there are different quotation mark conventions used in «Norwegian», ”Swedish”, »Danish«, „German”, and 「Japanese」.[3]

お使いの記法で文字列をカッコや角カッコ、引用符の間に置く場合は、メッセージの parentheses ($1) や brackets [$1] や quotation-marks 「$1」 を次のように応用します。 

wfMessage( 'parentheses' )->rawParams( /* カッコの間にはさむ文字列 */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* カッコのあいだにはさむ文字列 */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* 引用符の間にはさむ文字列 */ )->escaped()

記号や句読点が訳文にも引き継がれると予測しないこと

（英語と逆方向の右から左へ書く）左書き文字を採用する言語では、矢印記号を「次」や「前」というリンクに置換し、またその配置は文章の書字方向に合致させ、同じ向きもしくは反転させます。 省略記号は欧文なら「etc.」あるいはまたことばに翻訳します。 疑問符や感嘆符、コロンの配置は（訳注：翻訳後の言語によって）文末に固定されず、まったく使わない、あるいは2回使います（訳注：疑問文の前後など）。 それらを受けて、プログラムで挿入しようとしないで、メッセージに文字としてそれらすべてを記してください。

終止符(句点)の使用

平常文の文末は、必ず読点で終えます。 翻訳者の立場だと、原文が見出し、またはリストの一部ではないと判断する手がかりはそれしかない場合が多く、また、もしもそれらのどちらかならば、訳し方はまったく変える必要があります。

意味のあるリンクアンカーを使用する

アンカーを置くなら、参照元をきちんと示すように注意します。 ありふれた一般的な言葉はどんなときも使わないでください。 一例として、「ここをクリック」はまったく意味をなさず[4]、「ここをクリック」が参照元のページ自体ではあり得ないからです。 代わりに正確な指示語を使って、ユーザーがリンクをたどったときに何が現れるか、たとえば「希望するならファイルをアップロードしてください」などと伝えます。

利用者に次はどこへ進むか見える化するには ならびに謎肉を追うに加えてリンク文にここをクリックと示してはダメな主な理由 も参照しましょう。

専門用語やスラングを避ける

メッセージには技術者やヘビーユーザにしか通じない専門語は避けてください。つねに平明な用語を使いましょう。 利用者になにかの成否を伝えるとき「成功」「成功した」「失敗」「〇〇中にエラー発生」とは表現しないでください。 これは開発者目線ですべてを真か偽で判断してありますが、通常、利用者は実際に何が発生したかしなかったか、それに対して自分は（何かすることがあるなら）何をすれば良いかを知りたいだけです。そこで次の件をあげます。

  • 「ファイルはきちんと改名されました」 -> ファイルは改名済みです」
  • 「ファイルの改名に失敗しました」 -> 「同名のファイルがすでに存在します。違う名称を選んでください。」

空白や改行に気を付ける

MediaWiki ではローカライズ化したメッセージの編集を通常はウィキ内で処理し、運用中のウィキの運用者もしくは translatewiki.net で翻訳者が手がけます。 空白スペースは、特に文の冒頭もしくは末尾に置くと、それが編集者に与える影響をあらかじめ自覚しておく必要があります。

  • 空白記号と改行記号（行を変える記号）をメッセージの文末に置くと、ウィキテキスト編集では常に自動で除去します。メッセージ末尾に空白記号と改行記号を使ってもウィキが編集される時に除去されてしまうので、使ってはいけません。
  • 空白記号と改行記号を行頭においても自動で除去はしない代わりに使用はやめるべきで、編集中にうっかり除去されることが予想されるからです。

メッセージの先頭と末尾には、実際の文字を書いてください。そのどちらかの周辺で行を変えたい、段落を変えたい場合は、処理後の見た目がそうなるように、前後のコードで指定します。

文末に空白が必要なメッセージもいくつかあり、例えば word-separator があります (ほとんどの言語では単なる空白文字で構成されています)。 このようなユース ケースをサポートするために、以下の HTML エンティティがメッセージ内で使用可能であり、メッセージがウィキテキストや HTML の書式設定を許可していない場合でも、実際の文字に変換されます:[5]

関連の注記としては、pre-save transformsの影響を受ける他の構文要素もウィキでメッセージが編集されたときに変換されてしまうため、メッセージで使用しないでください。

標準的な大文字化の使用

大文字表記：翻訳者には作業対象が単語なのか、メニューもしくは項目一覧か、熟語あるいは文かどうか判断の材料になります。 正しい（標準）の大文字表記は検索エンジンが利用者のページ名の判断に役立てている場合があります。 MediaWiki ではインタフェースのメッセージ類に行頭の大文字を採用しています（例：The quick brown fox jumps over the lazy dog）。

常に忘れてはならないのは、多くの言語記法に大文字小文字の区別がないこと、また大文字小文字があったとしても英語とは記法のルールが異なるものもあることです。 したがって強調しようと大文字のみ（ALL-CAPS）を使うことは禁じられています。 以下に従い、CSS もしくは HTML ‎<em> または ‎<strong> を適用：

強調

平常文では、太字ないしは斜体 その他の強調（英語版）の書式はメッセージ本文の一部と見なすべきです。 強調に関するローカルの慣習はしばしば差異があり、特にアジアの複数の言語は個別に書字スクリプトを備えています。 翻訳者は訳出する言語ならびに地域に合うように、強調する範囲の調整を認められるべきです。 作業中の利用者インタフェースにはなるべく "‎<em>" と "‎<strong>" を使うと、言語単位もしくはスプリプト単体のマークアップをしやすくなります。

英語ならびに欧州諸語の最近の画面レイアウトでは、強調記号（emphasis）の使用はすっかり減りました。 それでも皆さんの書く#メッセージの説明文には盛り込んでおき、どう翻訳するか、重要なヒントになる可能性を残しておきます。 強調記号は、翻訳者がその他の文化的な文脈を理解している前提で、適切な場合に限定して採用します。

関連項目

注記

  1. ↑ 一部のリンターは、項目が 1 つしかないメッセージ リストを拒否します。例: mediawiki/msg-doc は項目が 1 つの有効な説明文書を受け付けません。
  2. ↑ http://dev.w3.org/csswg/css3-writing-modes/
  3. ↑ w:Quotation_mark#Summary_table
  4. ↑ http://www.w3.org/QA/Tips/noClickHere
  5. ↑ https://github.com/wikimedia/mediawiki/blob/REL1_34/includes/cache/MessageCache.php#L887
Retrieved from "https://www.mediawiki.org/w/index.php?title=Help:System_message/ja&oldid=8066693"