diff options
Diffstat (limited to 'files/ja/mozilla/add-ons/webextensions/internationalization/index.html')
| -rw-r--r-- | files/ja/mozilla/add-ons/webextensions/internationalization/index.html | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/files/ja/mozilla/add-ons/webextensions/internationalization/index.html b/files/ja/mozilla/add-ons/webextensions/internationalization/index.html new file mode 100644 index 0000000000..368cba4d29 --- /dev/null +++ b/files/ja/mozilla/add-ons/webextensions/internationalization/index.html @@ -0,0 +1,415 @@ +--- +title: 国際化 +slug: Mozilla/Add-ons/WebExtensions/Internationalization +tags: + - Article + - Guide + - Internationalization + - Localization + - WebExtensions + - i18n + - messages.json + - placeholders + - predefined messages +translation_of: Mozilla/Add-ons/WebExtensions/Internationalization +--- +<div>{{AddonSidebar}}</div> + +<p><a href="/ja/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> API には、拡張機能を国際化するとても簡単なモジュール — <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a> があります。この記事ではその機能を見てみて、どのように動作するのかの実例を提供します。WebExtensions API を使った拡張機能用の i18n システムは、<a href="http://i18njs.com/">i18n.js</a> のような、よくある i10n 用 JavaScript ライブラリーと同様です。</p> + +<div class="note"> +<p>この記事の見本の拡張機能— <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> — は GitHub で入手できます。以下の節を進んでいくのに合わせてコードを追ってください。</p> +</div> + +<h2 id="Anatomy_of_an_internationalized_extension" name="Anatomy_of_an_internationalized_extension">国際化拡張機能の中身</h2> + +<p>国際化された拡張機能は、他の拡張機能と同じ機能 — <a href="/ja/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">バックグラウンドスクリプト</a>、<a href="/ja/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">コンテンツスクリプト</a>など — を含む他、さまざまなロケールに切り替えられるような追加の部分もあります。これは下記のディレクトリーツリーのように要約されます:</p> + +<ul class="directory-tree"> + <li>extension-root-directory/ + <ul> + <li>_locales + <ul> + <li>en + <ul> + <li>messages.json + <ul> + <li>英語メッセージ (文字列)</li> + </ul> + </li> + </ul> + </li> + <li>de + <ul> + <li>messages.json + <ul> + <li>ドイツ語メッセージ (文字列)</li> + </ul> + </li> + </ul> + </li> + <li>etc.</li> + </ul> + </li> + <li>manifest.json + <ul> + <li>ロケール依存のメタデータ</li> + </ul> + </li> + <li>myJavascript.js + <ul> + <li>ブラウザーロケールや、ロケール固有メッセージなどを取得する JavaScript</li> + </ul> + </li> + <li>myStyles.css + <ul> + <li>ロケール依存の CSS</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>それぞれの新機能を順に見ていきましょう— 以下の節は拡張機能を国際化するときのそれぞれのステップを表しています。</p> + +<h2 id="Providing_localized_strings_in__locales" name="Providing_localized_strings_in__locales">_locales 内にローカライズ済み文字列を提供する</h2> + +<div class="pull-aside"> +<div class="moreinfo">言語のサブタグを探すには、<a href="https://r12a.github.io/app-subtags/">Language subtag lookup page</a> の検索ツールを使います。注意点としては言語の名前の英語で探す必要があります。</div> +</div> + +<p>すべての i18n システムはサポートする全ロケールに翻訳済みの文字列が要ります。拡張機能では、これは拡張機能のルート内に置かれる <code>_locales</code> と呼ばれるディレクトリーに入っています。各ロケールはそれぞれの文字列 (メッセージとも呼ばれる) を <code>messages.json</code> というファイル内に入れていて、これは <code>_locales</code> のサブディレクトリー内に置かれており、そこはロケール言語の言語サブタグを使った名前になっています。</p> + +<p>サブタグには基本的な言語に加えて、地域の異型があるのに注意してください。ここで言語と異型は伝統的にハイフンで区切られます: 例えば "en-US"。しかし、<code>_locales</code> 内のディレクトリーでは、<strong>区切り文字はアンダースコアでなければならず</strong>: "en_US"となります。</p> + +<p><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n/_locales">例えば、見本のアプリでは</a> "en" (英語), "de" (ドイツ語), "nl" (オランダ語), "ja" (日本語) のフォルダーがあります。それぞれの中に <code>messages.json</code> ファイルがあります。</p> + +<p>このファイル (<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/_locales/en/messages.json">_locales/en/messages.json</a>) の構造を見てみます:</p> + +<pre class="brush: json">{ + "extensionName": { + "message": "Notify link clicks i18n", + "description": "Name of the extension." + }, + + "extensionDescription": { + "message": "Shows a notification when the user clicks on links.", + "description": "Description of the extension." + }, + + "notificationTitle": { + "message": "Click notification", + "description": "Title of the click notification." + }, + + "notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } + } +}</pre> + +<p>このファイルは標準の JSON — メンバーがそれぞれに <code>message</code> と <code>description</code>. を含む名前付きオブジェクトです。すべての項目が文字列です; <code>$URL$</code> はプレースホルダーで、拡張機能から呼ばれる <code>notificationContent</code> メンバーに置き換えられます。{{anch("Retrieving message strings from JavaScript")}} 節でその方法を学びます。</p> + +<div class="note"> +<p><strong>注</strong>: <code>messages.json</code> ファイルの中身についての詳しい情報は<a href="/ja/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">ロケール固有のメッセージリファレンス</a>にあります。</p> +</div> + +<h2 id="Internationalizing_manifest.json" name="Internationalizing_manifest.json">manifest.json を国際化する</h2> + +<p>manifest.json の国際化を実行するにはいくつかの異なるタスクがあります。</p> + +<h3 id="Retrieving_localized_strings_in_manifests" name="Retrieving_localized_strings_in_manifests">マニフェスト内のローカライズ済み文字列を取得する</h3> + +<p><a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/manifest.json">manifest.json</a> にはユーザーに表示される文字列が入っています、例えば拡張機能の名前や説明です。この文字列を国際化して messages.json に適切な訳を置くと、現在のロケールなどに基づき、正しく翻訳された文字列がユーザーに表示されます。</p> + +<p>文字列を国際化するには、このように指定します:</p> + +<pre class="brush: json">"name": "__MSG_extensionName__", +"description": "__MSG_extensionDescription__",</pre> + +<p>ここで、単なる固定文字列ではなく、ブラウザーのロケールに依存しないメッセージ文字列を取得します。</p> + +<p>このようなメッセージ文字列を呼び出すには、次のように指定します:</p> + +<ol> + <li>2 つのアンダースコアに続いて</li> + <li>"MSG" という文字列に続いて</li> + <li>1 つのアンダースコアに続いて</li> + <li><code>messages.json</code> で定義した呼び出しのメッセージ名に続いて</li> + <li>2 つのアンダースコア</li> +</ol> + +<pre><strong>__MSG_</strong> + <em>messageName</em> + <strong>__</strong></pre> + +<h3 id="Specifying_a_default_locale" name="Specifying_a_default_locale">デフォルトロケールを指定する</h3> + +<p>manifest.json にて指定すべきフィールドは <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a> です:</p> + +<pre class="brush: json">"default_locale": "en"</pre> + +<p>これは拡張機能がブラウザーの現在のロケールに対するロケール文字列を含んでいない場合のデフォルトロケールを指定します。ブラウザーロケールで利用できないあらゆるメッセージ文字列が代わりのデフォルトロケールとして引受られます。ブラウザーが文字列を選ぶ方法に関して意識すべき詳細な点があります — {{anch("Localized string selection")}} を見てください。</p> + +<h2 id="Locale-dependent_CSS" name="Locale-dependent_CSS">ロケールに依存しない CSS</h2> + +<p>拡張機能の CSS ファイルからもローカライズされた文字列を取得できます。例えば、ロケールに依存しない CSS を組み立てるなら、このようにします:</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_extensionName__/header.png); +}</pre> + +<p>{{anch("Predefined messages")}} を使ってこんな状況を扱う方がより良いものの、これは便利です。</p> + +<h2 id="Retrieving_message_strings_from_JavaScript" name="Retrieving_message_strings_from_JavaScript">JavaScript からメッセージ文字列を取得する</h2> + +<p>それで、メッセージ文字列とマニフェストがセットアップできました。今は単に JavaScript からメッセージ文字列を呼び出して、拡張機能ができるだけ多くの正しい言語を話すようにします。実際の <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n API</a> はとてもシンプルで、そこには 4 つのメソッドがあります:</p> + +<ul> + <li>たぶん一番多く {{WebExtAPIRef("i18n.getMessage()")}} を使うでしょう — これは上記に触れられたとおり、特定の文字列を取得するのに使うメソッドです。これの使用例は下記で見ます。</li> + <li>{{WebExtAPIRef("i18n.getAcceptLanguages()")}} と{{WebExtAPIRef("i18n.getUILanguage()")}} メソッドはロケールに応じて UI をカスタマイズする場合に使います — たぶんユーザーの好みの言語に応じて設定リストの上の方に表示したり、特定言語だけに関連する文化的情報を表示したり、ブラウザーロケールに従って日付表示を整形したりすると良いでしょう。</li> + <li>{{WebExtAPIRef("i18n.detectLanguage()")}} メソッドはユーザーが投稿したコンテンツの言語を特定したり、それを適切に整形したりするのに使います。</li> +</ul> + +<p><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> の見本の中で、<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/background-script.js">バックグラウンドスクリプト</a>に下記の行があります:</p> + +<pre class="brush: js">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url);</pre> + +<p>最初は単に <code>messages.json</code> ファイルからブラウザーの現ロケールのための <code>notificationTitle message</code> 項目を取得します。2 つ目は同様ですが、2 つ目のパラメーターに URL を渡されます。これは何でしょう？これは <code>notificationContent message</code> 項目の中の <code>$URL$</code> プレースホルダーを置き換えるためにコンテンツを指定する方法です: </p> + +<pre class="brush: json">"notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } +} +</pre> + +<p><code>"placeholders"</code> メンバーはプレースホルダーを定義し、ここから取得します。<code>"url"</code> プレースホルダーは $1、つまり 2 つ目のパラメーターの <code>getMessage()</code>.の最初の値から取ってきたコンテンツを指定します。プレースホルダーは<code>"url"</code> と呼ばれるため、実際のメッセージ文字列の中で呼び出すのに <code>$URL$</code> を使います (なので <code>"name"</code> には <code>$NAME$</code>などを使う)。複数のプレースホルダーがある場合、{{WebExtAPIRef("i18n.getMessage()")}} の 2 つ目のパラメーターとして渡す配列の中で提供できます — <code>messages.json</code> 内部で <code>[a, b, c]</code> は<code>$1</code>, <code>$2</code>, <code>$3</code>, として使われる、など。</p> + +<p>例をざっと見ましょう: <code>en/messages.json</code> ファイル内のオリジナルの <code>notificationContent</code> メッセージ文字列はこうです</p> + +<pre>You clicked $URL$.</pre> + +<p><code>https://developer.mozilla.org</code> を指すリンクがクリックされたとします。{{WebExtAPIRef("i18n.getMessage()")}} を呼び出した後、2 つ目のパラメーターのコンテンツは messages.json 内で <code>$1</code> として利用できて、これは <code>"url"</code> プレースホルダー内で定義された <code>$URL$</code> プレースホルダーを置換します。よって最終のメッセージ文字列はこうなります</p> + +<pre>You clicked https://developer.mozilla.org.</pre> + +<h3 id="Direct_placeholder_usage" name="Direct_placeholder_usage">直接プレースホルダーを使う</h3> + +<p>メッセージ文字列の中に直接に変数 (<code>$1</code>, <code>$2</code>, <code>$3</code> など) を挿入できます。例えば上記の <code>"notificationContent"</code> メンバーをこう書き換えてみます:</p> + +<pre class="brush: json">"notificationContent": { + "message": "You clicked $1.", + "description": "Tells the user which link they clicked." +}</pre> + +<p>これはややこしくなくて速いように見えますが、他の方法 (<code>"プレースホルダー"</code>を使う)が最も良いやり方です。これはプレースホルダー名 (例えば<code>"url"</code>) や例によって、プレースホルダーの目的を思い出せます — コードを書いた 1週間後には、<code>$1</code>–<code>$8</code> が何を指すか忘れているでしょうが、プレースホルダー名が何を指すかならもっと思い出しやすいでしょう。</p> + +<h3 id="Hardcoded_substitution" name="Hardcoded_substitution">ハードコーディングされた置き換え</h3> + +<p>プレースホルダーにハードコードされた文字列を入れることもできます、これでコード内の変数の代わりに、いつでも同じ値が使われます。例えば:</p> + +<pre class="brush: json">"mdn_banner": { + "message": "For more information on web technologies, go to $MDN$.", + "description": "Tell the user about MDN", + "placeholders": { + "mdn": { + "content": "https://developer.mozilla.org/" + } + } +}</pre> + +<p>ここでは、<code>$1</code> といった変数から取るのではなく、プレースホルダーの content をハードコードしています。これはメッセージが複雑で、ファイル内で読みやすくするために色々な値に分割したい時に役立ちますし、さらにこの値はプログラム的にアクセスすることもできます。</p> + +<p>それに加えて、個人やビジネス名といった翻訳したくない文字列を、このような置き換えから指定するのに使うことができます。</p> + +<h2 id="Localized_string_selection" name="Localized_string_selection">ローカライズ済みの文字列の選択</h2> + +<p>ロケールは <code>fr</code> や <code>en</code> のような言語コードによってのみ指定されるか、さらに <code>en_US</code> や <code>en_GB</code> といった地域コードつきで (これは同じ言語の地域的な変形を記述します) 認証されます。i18n に文字列を問い合わせた時、次のアルゴリズムで文字列を選択します:</p> + +<ol> + <li>現在のロケールと全く同じ <code>messages.json</code> ファイルがあって、そこに文字列が入っている場合、それを返します</li> + <li>それ以外で、現在のロケールが地域つきで認証されて (例<code>en_US</code>) 、そのロケールの地域になし版の <code>messages.json</code> ファイルがあって (例<code>en</code>)、そこに文字列が入っている場合、それを返します</li> + <li>それ以外で、<code>manifest.json</code>内に定義された <code>default_locale</code> 用の <code>messages.json</code> ファイルがあって、そこに文字列が入っている場合、それを返します</li> + <li>それ以外は空文字を返します</li> +</ol> + +<p>下記の例を見てみます:</p> + +<ul class="directory-tree"> + <li>extension-root-directory/ + <ul> + <li>_locales + <ul> + <li>en_GB + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + en + + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "color", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + </li> + <li>fr + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "<span lang="fr">couleur</span>", "description": "Color." }, ...}</code></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> +</ul> + +<p><code>default_locale</code> が <code>fr</code> にセットされ、ブラウザーの現在のロケールが <code>en_GB</code> と仮定します:</p> + +<ul> + <li>拡張機能が <code>getMessage("colorLocalised")</code>を呼び出すと、"colour"を返します</li> + <li><code>en_GB</code> に "colorLocalised" がなかったとしたら、<code>getMessage("colorLocalised")</code> は"couleur" でなく "color" を返します</li> +</ul> + +<h2 id="Predefined_messages" name="Predefined_messages">事前定義されたメッセージ</h2> + +<p>i18n モジュールでは、事前定義されたメッセージを提供しており、これまで見てきた{{anch("Calling message strings from manifests and extension CSS")}} と同じ方法で呼び出すことができます。例えばこのように:</p> + +<pre>__MSG_extensionName__</pre> + +<p>事前定義されたメッセージでも全く同じ文法を使っていますが、メッセージ名の前に <code>@@</code> をつけるのが異なります、その例は</p> + +<pre>__MSG_@@ui_locale__</pre> + +<p>下記の表は利用可能なさまざまな事前定義されたメッセージ:を示しています:</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">メッセージ名</th> + <th scope="col">説明</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>@@extension_id</code></td> + <td> + <p>拡張機能の内部生成された UUID。この文字列は拡張機能内のリソースの URL を作るのに使います。. ローカライズされた拡張機能でもこのメッセージを使用できます。</p> + + <p>このメッセージをマニフェストファイル内で使用することはできません。</p> + + <p>もう一つの注意点として、この ID は {{WebExtAPIRef("runtime.id")}} から返される、manifest.json 内の<a href="/ja/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications"> applications </a>キーを用いてセットされるアドオン ID とは異なっています。これはアドオンの URL内にある生成された UUID です。つまりこの値を{{WebExtAPIRef("runtime.sendMessage()")}} の <code>extensionId</code> パラメーターの値として使うことはできず、{{WebExtAPIRef("runtime.MessageSender")}} オブジェクトの <code>id</code> プロパティの値のチェックに使うこともできません。</p> + </td> + </tr> + <tr> + <td><code>@@ui_locale</code></td> + <td>現在のロケールで、この文字列をロケール固有の URL 生成に使うことができます。</td> + </tr> + <tr> + <td><code>@@bidi_dir</code></td> + <td>現在のロケールにおけるテキストの向きで、英語のような左から右の言語では "ltr" で、アラビア語のような右から左への言語では "rtl" となり、このいずれかです。</td> + </tr> + <tr> + <td><code>@@bidi_reversed_dir</code></td> + <td><code>@@bidi_dir</code> が "ltr" なら "rtl" で、そうでなれば "ltr" です。</td> + </tr> + <tr> + <td><code>@@bidi_start_edge</code></td> + <td><code>@@bidi_dir</code> が "ltr" なら "left" で、そうでなれば "right" です。</td> + </tr> + <tr> + <td><code>@@bidi_end_edge</code></td> + <td><code>@@bidi_dir</code> が "ltr" なら "right" で、そうでなれば "left" です。</td> + </tr> + </tbody> +</table> + +<p>前の例に戻って、次のように書いてみるともっと意味がわかります:</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_@@ui_locale__/header.png); +}</pre> + +<p>サポートしているロケール(en, de など)にマッチしたディレクトリー内にロケール固有の画像を保管しているとすると、もっとわかり良いです。</p> + +<p>CSS ファイル内で <code>@@bidi_*</code> メッセージを使った次の例を見てみましょう:</p> + +<pre class="brush: css">body { + direction: __MSG_@@bidi_dir__; +} + +div#header { + margin-bottom: 1.05em; + overflow: hidden; + padding-bottom: 1.5em; + padding-__MSG_@@bidi_start_edge__: 0; + padding-__MSG_@@bidi_end_edge__: 1.5em; + position: relative; +}</pre> + +<p>英語のような左から右への言語では、上の事前定義されたメッセージを含んだ CSS 定義は、下記の最終コード行に変換されます:</p> + +<pre class="brush: css">direction: ltr; +padding-left: 0; +padding-right: 1.5em; +</pre> + +<p>アラビア語のような右から左への言語では、次を得ます:</p> + +<pre class="brush: css">direction: rtl; +padding-right: 0; +padding-left: 1.5em;</pre> + +<h2 id="Testing_out_your_extension" name="Testing_out_your_extension">あなたの拡張機能をテストする</h2> + +<p>Firefox 45 からは、拡張機能を一時的にディスクからインストールできます — <a href="https://developer.mozilla.org/ja/Add-ons/WebExtensions/Packaging_and_installation#Loading_from_disk">ディスクから読み込む</a>を見てください。これを行ってから、<a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 拡張機能をテストしてみます。お好きなウェブサイトに移動してクリックしたリンクの URL を報告した通知が出てくるか見てください。</p> + +<p>次に、Firefox のロケールをテストしたい拡張機能がサポートするものに変えます。</p> + +<ol> + <li>Firefox で"about:config"を開き、<code>intl.locale.requested</code> の設定を探します (Firefox 59 より前では、この設定は <code>general.useragent.locale</code> と呼ばれます)。</li> + <li>設定がある場合、それをダブルクリックして (または Return/Enter を押して) 選択し、テストしたいロケールの言語コードを入力して"OK" をクリックします (または Return/Enter を押す)。例えば我々の例では "en" (英語), "de" (ドイツ語), "nl" (オランダ語), "ja" (日本語) がサポートされます。空文字(<code>""</code>)をセットすることもできて、そうするとブラウザーは OS のデフォルトロケールを使います。</li> + <li><code>intl.locale.requested</code> の設定が存在しない場合、設定リストを右クリックします (あるいはキーボードからコンテキストメニューを起動します)、そして"New" と "String"を選びます。設定名に <code>intl.locale.requested</code> を入力して、上記ステップ 2 の説明の通りに "de" や "nl" などの値を設定値に入力します。</li> + <li><code>intl.locale.matchOS</code> を探してその設定をダブルクリックし、<code>false</code> に設定します。</li> + <li>ブラウザーを再起動して変更を完了します。</li> +</ol> + +<div class="note"> +<p><strong>注</strong>: これはブラウザーのロケールを変更させる動作で、この言語用の<a href="https://addons.mozilla.org/en-US/firefox/language-tools/">言語パック</a>がインストールされていなくてもそうなります。その場合はブラウザー UI はデフォルト言語となります。</p> +</div> + +<ol> +</ol> + +<div class="note"> +<p><strong>注:</strong> <code>getUILanguage</code> の結果を変更するには言語パックが要求されます、これはブラウザー UI 言語を変更して拡張機能メッセージ用の言語は変更しないためです。</p> +</div> + +<p>ディスクから拡張機能を読み込み直して、新しいロケールをテストします</p> + +<ul> + <li>もう一度 "about:addons" へ移動します — 拡張機能が一覧となり、アイコンと、選択した言語での名前と説明があるのが見えます。</li> + <li>拡張機能をまたテストします。我々の見本では、他のウェブサイトでリンクをクリックして、通知が選択した言語で出てくるのが見えます。</li> +</ul> + +<p>{{EmbedYouTube("R7--fp5pPGg")}}</p> |