chrome.i18n

説明

chrome.i18n インフラストラクチャを使用して、アプリまたは拡張機能全体に国際化を実装します。

マニフェスト

拡張機能に /_locales ディレクトリがある場合は、マニフェストで "default_locale" を定義する必要があります。

コンセプトと使用方法

ユーザーに表示されるすべての文字列を、messages.json という名前のファイルに配置する必要があります。新しい言語 / 地域を追加するたびに、/_locales/_localeCode_ という名前のディレクトリにメッセージ ファイルを追加します。ここで、localeCode は、英語の場合は en などのコードです。

英語（en）、スペイン語（es）、韓国語（ko）をサポートする国際化済み拡張機能のファイル階層は次のとおりです。

拡張機能のディレクトリ: manifest.json、*.html、*.js、/_locates ディレクトリ。/_locates ディレクトリ: en、es、ko ディレクトリ。それぞれ messages.json ファイルがあります。

複数言語の対応

次の図に示すファイルの拡張子があるとします。

manifest.json ファイルと JavaScript を含むファイル。.json ファイルには、

この拡張機能を国際化するには、ユーザーに表示される各文字列に名前を付け、メッセージ ファイルに入れます。拡張機能のマニフェスト、CSS ファイル、JavaScript コードでは、各文字列の名前を使用してローカライズ版を取得します。

国際化した拡張機能は次のようになります（ただし、まだ英語の文字列しかありません）。

<b

国際化に関する注意事項:

  • サポートされている言語 / 地域のどれでも使用できます。サポートされていない言語 / 地域を使用した場合、Google Chrome では無視されます。

  • manifest.json ファイルと CSS ファイルで、次のように messagename という名前の文字列を参照します。

    __MSG_messagename__

  • 拡張機能またはアプリの JavaScript コードで、次のように messagename という名前の文字列を参照します。

    chrome.i18n.getMessage("messagename")

  • getMessage() の呼び出しごとに、メッセージに含める文字列を 9 つまで指定できます。詳しくは、例: getMessage をご覧ください。

  • @@bidi_dir や @@ui_locale などの一部のメッセージは、国際化システムにより提供されます。定義済みのメッセージ名の一覧については、事前定義されたメッセージのセクションをご覧ください。

  • messages.json では、ユーザーに表示される各文字列には、名前、メッセージ項目、説明項目（省略可）が含まれます。名前は、「extName」や「search_string」など、文字列を識別するキーです。"message" は、このロケールでの文字列の値を指定します。オプションの「description」は翻訳者に役立ちます。拡張機能で文字列がどのように使用されているかがわからない可能性があります。次に例を示します。

    {
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}

詳細については、形式: ロケール固有のメッセージをご覧ください。

国際化した拡張機能は簡単に翻訳できます。messages.json をコピーして翻訳し、そのコピーを /_locates の下の新しいディレクトリに配置します。たとえば、スペイン語をサポートするには、messages.json の翻訳コピーを /_locates/es に配置します。次の図は、新たにスペイン語に翻訳された前の拡張機能を示しています。

上の画像と同じですが、/_locates/es/messages.json に新しいファイルが追加されます。このファイルにはメッセージのスペイン語翻訳が含まれます。

定義済みのメッセージ

国際化システムには、ローカライズに役立つ事前定義メッセージがいくつか用意されています。これらには、現在の UI ロケールを検出するための @@ui_locale と、テキスト方向を検出するためのいくつかの @@bidi_... メッセージが含まれます。後者のメッセージは、ガジェットの BIDI（双方向）API の定数と同様の名前を持ちます。

特別なメッセージ @@extension_id は、拡張機能やアプリがローカライズされているかどうかにかかわらず、CSS ファイルと JavaScript ファイルで使用できます。このメッセージは、マニフェスト ファイルでは機能しません。

次の表に、事前定義された各メッセージを示します。

メッセージ名説明
@@extension_id拡張機能またはアプリ ID。この文字列を使用して、拡張機能内のリソースの URL を作成できます。ローカライズされていない拡張機能でも、このメッセージを使用できます。
注: このメッセージは、マニフェスト ファイルでは使用できません。
@@ui_locale現在の言語 / 地域。この文字列を使用して、言語 / 地域固有の URL を作成できます。
@@bidi_dir現在の言語 / 地域のテキスト方向。左から右に表記する言語（英語など）の場合は「ltr」、アラビア語など右から左に表記する言語の場合は「rtl」のいずれかです。
@@bidi_reversed_dir@@bidi_dir が「ltr」の場合は「rtl」、それ以外の場合は「ltr」です。
@@bidi_start_edge@@bidi_dir が「ltr」の場合は「left」、それ以外の場合は「right」です。
@@bidi_end_edge@@bidi_dir が「ltr」の場合は「right」、それ以外の場合は「left」になります。

以下は、CSS ファイルで @@extension_id を使用して URL を作成する例です。

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

拡張機能 ID が abcdefghijklmnopqrstuvwxyzabcdef の場合、前のコード スニペットの太字行は次のようになります。

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

CSS ファイルで @@bidi_* メッセージを使用する例を次に示します。

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;
}

英語のように左から右に表記する言語の場合、太字の行は次のようになります。

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

言語 / 地域

1 つの翻訳で 1 つの言語の複数のバリエーションをサポートできる言語 / 地域（en など）を含め、さまざまな言語 / 地域から選択できます（en_GB と en_US など）。

拡張機能は、Chrome ウェブストアでサポートされているすべての言語 / 地域にローカライズできます。お住まいの地域にない場合は、最も近い言語 / 地域を選択してください。たとえば、拡張機能のデフォルトの言語 / 地域が "de_CH" の場合は、Chrome ウェブストアで "de" を選択します。

言語 / 地域コード 言語（地域）
ar アラビア語
am アムハラ語
bg ブルガリア語
bn ベンガル語
ca カタロニア語
cs チェコ語
da デンマーク語
de ドイツ語
el ギリシャ語
en 英語
en_AU 英語 (オーストラリア)
en_GB 英語（英国）
en_US 英語（アメリカ）
es スペイン語
es_419 スペイン語（ラテンアメリカ、カリブ海）
et エストニア語
fa ペルシャ語
fi フィンランド語
fil フィリピン語
fr フランス料理
gu グジャラート語
he ヘブライ語
hi ヒンディー語
時間 クロアチア語
hu ハンガリー語
id インドネシア語
送信できます イタリア語
ja 日本語
kn カンナダ語
ko 韓国語
lt リトアニア語
lv ラトビア語
ml マラヤーラム語
mr マラーティー語
ミリ秒 マレー語
nl オランダ語
× ノルウェー語
pl ポーランド語
pt_BR ポルトガル語（ブラジル）
pt_PT ポルトガル語 (ポルトガル)
ro ルーマニア語
ru ロシア語
sk スロバキア語
sl スロベニア語
sr セルビア語
sv スウェーデン語
sw スワヒリ語
ta タミル文字
te テルグ文字
th タイ語
tr トルコ語
uk ウクライナ語
vi ベトナム語
zh_CN 中国語（中国）
zh_TW 中国語（台湾）

メッセージを検索する

サポートされている言語 / 地域ごとにすべての文字列を定義する必要はありません。デフォルトのロケールの messages.json ファイルにすべての文字列の値が指定されていれば、拡張機能やアプリは翻訳がどれだけまばらであっても実行されます。拡張機能システムがメッセージを検索する仕組みは次のとおりです。

  1. メッセージ ファイル（存在する場合）でユーザーが使用する言語 / 地域を検索します。たとえば、Google Chrome のロケールがイギリス英語（en_GB）に設定されている場合、システムはまず /_locates/en_GB/messages.json でメッセージを探します。そのファイルが存在し、メッセージが存在している場合、システムは何も検索しません。
  2. ユーザーが希望する言語 / 地域に地域が含まれている場合（つまり、言語 / 地域にアンダースコア（_）が付いている場合、その地域のない言語 / 地域を検索します。たとえば、en_GB メッセージ ファイルが存在しない場合、またはメッセージが含まれていない場合、システムは en メッセージ ファイルを検索します。そのファイルが存在し、メッセージが存在している場合、システムは検索しなくなります。
  3. メッセージ ファイルでデフォルトの言語 / 地域を検索します。たとえば、拡張機能の「default_locale」が「es」に設定されていて、/_locates/en_GB/messages.json と /_locates/en/messages.json のどちらにもメッセージが含まれていない場合、拡張機能は /_locates/es/messages.json からのメッセージを使用します。

次の図では、「colores」というメッセージは拡張機能がサポートする 3 つのロケールすべてにありますが、「extName」はそのうちの 2 つにのみ存在します。英語（米国）で Google Chrome を実行しているユーザーには「カラー」というラベルが表示されますが、イギリス英語での使用ユーザーには「カラー」が表示されます。英語（米国）と英語（英国）のユーザーには、拡張機能の名前が「Hello World」と表示されます。デフォルトの言語はスペイン語であるため、英語以外の言語で Google Chrome を実行しているユーザーには、「Colores」というラベルと「Hola mundo」という拡張機能名が表示されます。

4 つのファイル: manifest.json と 3 つの messages.json ファイル（es、en、en_GB 用）。es ファイルと en ファイルには、名前を付けたメッセージのエントリが

ブラウザの言語 / 地域を設定する

翻訳をテストするには、ブラウザの言語 / 地域を設定できます。このセクションでは、Windows、Mac OS X、Linux、ChromeOS で言語 / 地域を設定する方法について説明します。

Windows

言語 / 地域固有のショートカットまたは Google Chrome UI を使用して言語 / 地域を変更できます。ショートカットは一度設定するとより高速になり、同時に複数の言語を使用できるようになります。

言語 / 地域固有のショートカットを使用する

特定の言語 / 地域で Google Chrome を起動するショートカットを作成、使用するには:

  1. デスクトップにすでにある Google Chrome のショートカットのコピーを作成します。
  2. 新しいショートカットの名前を新しい言語 / 地域に合わせて変更します。

  3. Target フィールドに --lang フラグと --user-data-dir フラグを指定するように、ショートカットのプロパティを変更します。ターゲットは、次のようになります。

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir

  4. ショートカットをダブルクリックして Google Chrome を起動します。

たとえば、スペイン語（es）で Google Chrome を起動するショートカットを作成するには、次のターゲットを持つ chrome-es という名前のショートカットを作成します。

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

ショートカットはいくつでも作成できるため、複数の言語で簡単にテストできます。次に例を示します。

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko
管理画面を使用する

Windows 版 Google Chrome で UI を使用して言語 / 地域を変更する方法は次のとおりです。

  1. アプリアイコン > オプション
  2. [高度な設定] タブを選択します。
  3. [ウェブ コンテンツ] まで下にスクロールします。
  4. [フォントや言語を変更] をクリックします。
  5. [言語] タブを選択します。
  6. プルダウンを使用して、Google Chrome の言語を設定します。
  7. Chrome を再起動する

Mac OS X

Mac で言語 / 地域を変更するには、システム環境設定を使用します。

  1. Apple メニューから [システム環境設定] を選択します。
  2. [Personal] セクションで [International] を選択します。
  3. 言語と地域を選択
  4. Chrome を再起動する

Linux

Linux の言語 / 地域を変更するには、まず Google Chrome を終了します。次に、すべて 1 行で環境変数 LANGUAGE を設定し、Google Chrome を起動します。次に例を示します。

LANGUAGE=es ./chrome

ChromeOS

ChromeOS で言語 / 地域を変更するには:

  1. システムトレイから [設定] を選択します。
  2. [言語と入力] セクションで [言語] プルダウンを選択します。
  3. 使用する言語がリストにない場合は、[言語を追加] をクリックして追加します。
  4. 追加したら、言語の横にある [その他の操作] メニュー項目をクリックし、[ChromeOS をこの言語で表示] を選択します。
  5. 設定した言語の横に表示される [再起動] ボタンをクリックして、ChromeOS を再起動します。

例

国際化の簡単な例は、examples/api/i18n ディレクトリにあります。詳細な例については、examples/extensions/news をご覧ください。他の例とソースコードの表示については、サンプルをご覧ください。

getMessage()

次のコードは、ローカライズされたメッセージをブラウザから取得して文字列として表示します。メッセージ内の 2 つのプレースホルダを文字列「string1」と「string2」に置き換えます。

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

1 つの文字列を指定して使用する方法は次のとおりです。

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

プレースホルダの詳細については、言語 / 地域固有のメッセージのページをご覧ください。getMessage() の呼び出しについて詳しくは、API リファレンスをご覧ください。

getAcceptLanguages()

次のコードでは、ブラウザから accept-language を取得し、それぞれの accept-language を「,」で区切って文字列として表示します。

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

getAcceptLanguages() の呼び出しの詳細については、API リファレンスをご覧ください。

detectLanguage()

次のコードは、指定された文字列から最大 3 つの言語を検出し、結果を改行で区切った文字列として表示します。

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

detectLanguage(inputText) の呼び出しについて詳しくは、API リファレンスをご覧ください。

型

LanguageCode

Chrome 47 以降

ISO 言語コード（en、fr など）。このメソッドでサポートされている言語の一覧については、kLanguageInfoTable をご覧ください。不明な言語の場合は und が返されます。これは、テキストの [percentage] が CLD に認識されていないことを意味します。

タイプ

string

メソッド

detectLanguage()

Promise Chrome 47 以降 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

CLD を使用して、指定されたテキストの言語を検出します。

パラメータ

  • 指定しています

    string

    翻訳対象のユーザー入力文字列。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (result: object) => void

    • 件の結果

      オブジェクト

      検出された言語の信頼性と DetectedLanguage の配列を保持する LanguageDetectionResult オブジェクト。

      • isReliable

        boolean

        CLD で検出された言語の信頼性

      • 言語

        オブジェクト []

        検出された言語の配列

        • language

          string

        • パーセンテージ

          数値

          検出された言語の割合

戻り値

  • Promise<object>

    Chrome 99 以降

    Promise は Manifest V3 以降でサポートされていますが、下位互換性のためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise はコールバックに渡された型と同じ型で解決されます。

getAcceptLanguages()

Promise 
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

ブラウザの受け入れ言語を取得します。これはブラウザで使用される言語 / 地域とは異なります。言語 / 地域を取得するには、i18n.getUILanguage を使用します。

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (languages: string[]) => void

    • 言語

      string[]

      LanguageCode の配列

戻り値

  • Promise<LanguageCode[]>

    Chrome 99 以降

    Promise は Manifest V3 以降でサポートされていますが、下位互換性のためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise はコールバックに渡された型と同じ型で解決されます。

getMessage()

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

指定されたメッセージのローカライズされた文字列を取得します。メッセージがない場合、このメソッドは空の文字列（''）を返します。getMessage() 呼び出しの形式が正しくない場合（たとえば、messageName が文字列ではない、substitutions 配列に 9 個を超える要素がある）場合、このメソッドは undefined を返します。

パラメータ

  • messageName

    string

    messages.json ファイルで指定されているメッセージの名前。

  • substitutions

    任意

    最大 9 個までの置換文字列（メッセージに必要な場合）。

  • オプション

    オブジェクト（省略可）

    Chrome 79 以降
    • escapeLt

      ブール値（省略可）

      < を &lt; に翻訳してエスケープします。これはメッセージ自体にのみ適用され、プレースホルダには適用されません。翻訳が HTML のコンテキストで使用される場合、デベロッパーはこのオプションを使用することをおすすめします。Closure Compiler で使用するクロージャ テンプレートでは自動的に生成されます。

戻り値

  • string

    現在の言語 / 地域に合わせてローカライズされたメッセージ。

getUILanguage()

chrome.i18n.getUILanguage()

ブラウザの UI 言語を取得します。これは、ユーザーの優先言語を返す i18n.getAcceptLanguages とは異なります。

戻り値

  • string

    ブラウザの UI 言語コード（en-US、fr-FR など）。