browser.i18n

說明

使用 chrome.i18n 基礎架構，在整個應用程式或擴充功能中實作國際化。

資訊清單

如果擴充功能有 /_locales 目錄，資訊清單必須定義 "default_locale"。

概念和用途

您需要將所有使用者可見的字串放入名為 messages.json 的檔案中。每次新增語言代碼時，您都要在名為 /_locales/_localeCode_ 的目錄下新增訊息檔案，其中 localeCode 是代碼，例如 en 代表英文。

以下是支援英文 (en)、西班牙文 (es) 和韓文 (ko) 的國際化擴充功能檔案階層：

在擴充功能目錄中：manifest.json、*.html、*.js、/_locales 目錄。在 /_locales 目錄中：en、es 和 ko 目錄，每個目錄都有一個 messages.json 檔案。

支援多種語言

假設您有一個擴充功能，其中包含下圖所示的檔案：

manifest.json 檔案和 JavaScript 檔案。.json 檔案含有「Hello World」。JavaScript 檔案的標題為「Hello World」。

如要將這個擴充功能國際化，請為每個使用者可見的字串命名，並將其放入訊息檔案中。擴充功能的資訊清單、CSS 檔案和 JavaScript 程式碼會使用每個字串的名稱，取得其本地化版本。

以下是國際化後的擴充功能 (請注意，其中仍只有英文字串)：

在 manifest.json 檔案中，「Hello World」已變更為「__MSG_extName__」，且新的 default_locale 項目值為「en」。在 JavaScript 檔案中，「Hello World」已變更為 browser.i18n.getMessage('extName')。名為 /_locales/en/messages.json 的新檔案會定義「extName」。

國際化注意事項：

  • 你可以使用任何支援的語言代碼。如果使用不支援的語言代碼，Google Chrome 會忽略該代碼。

  • 在 manifest.json 和 CSS 檔案中，請按照下列方式參照名為 messagename 的字串：

    __MSG_messagename__

  • 在擴充功能或應用程式的 JavaScript 程式碼中，請按照下列方式參照名為 messagename 的字串：

    browser.i18n.getMessage("messagename")

  • 每次呼叫 getMessage() 時，您最多可以提供 9 個字串，包含在訊息中。詳情請參閱「範例：getMessage」。

  • 部分訊息 (例如 @@bidi_dir 和 @@ui_locale) 是由國際化系統提供。如需預先定義訊息名稱的完整清單，請參閱「預先定義訊息」一節。

  • 在 messages.json 中，每個使用者可見的字串都有名稱、「message」項目和選用的「description」項目。名稱是「extName」或「search_string」等鍵，用於識別字串。「message」會指定這個語言代碼中的字串值。選用的「說明」可為翻譯人員提供協助，因為他們可能無法瞭解字串在擴充功能中的使用方式。例如：

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

詳情請參閱「格式：語言代碼專屬訊息」。

擴充功能國際化後，翻譯就變得簡單。複製 messages.json 並翻譯，然後將副本放入 /_locales 下的新目錄。舉例來說，如要支援西班牙文，只要將 messages.json 的翻譯版本放在 /_locales/es 下方即可。下圖顯示先前的擴充功能，並附上新的西班牙文翻譯。

這張圖與前一張圖相同，但 /_locales/es/messages.json 有一個新檔案，其中包含訊息的西班牙文翻譯。

預先定義的訊息

國際化系統提供一些預先定義的訊息，協助您進行本地化。包括 @@ui_locale，可偵測目前的使用者介面語言代碼，以及一些可偵測文字方向的 @@bidi_... 訊息。後者的訊息名稱與小工具 BIDI (雙向) API 中的常數類似。

無論擴充功能或應用程式是否經過本地化，都可以在 CSS 和 JavaScript 檔案中使用特殊訊息 @@extension_id。這則訊息不適用於資訊清單檔案。

下表說明各個預先定義的訊息。

訊息名稱說明
@@extension_id擴充功能或應用程式 ID；您可以使用這個字串，為擴充功能中的資源建構網址。即使是未本地化的擴充功能，也可以使用這則訊息。
注意：您無法在資訊清單檔案中使用這則訊息。
@@ui_locale目前的語言代碼；您可以使用這個字串建構語言代碼專屬網址。
@@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 建構網址：

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;

語言代碼

您可以從多個語言代碼中選擇，包括一些 (例如 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 北印度文
hr 克羅埃西亞文
hu 匈牙利文
id 印尼文
it 義大利文
ja 日文
kn 卡納達文
ko 韓文
lt 立陶宛文
lv 拉脫維亞文
ml 馬拉雅拉姆文
mr 馬拉地文
ms 馬來文
nl 荷蘭文
no 挪威文
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)，系統會先在 /_locales/en_GB/messages.json 中尋找訊息。如果該檔案存在且訊息在其中，系統就不會再繼續尋找。
  2. 如果使用者偏好的語言代碼包含地區 (即語言代碼包含底線：_)，請搜尋不含該地區的語言代碼。舉例來說，如果 en_GB 訊息檔案不存在或不含訊息，系統就會在 en 訊息檔案中尋找。如果該檔案存在且訊息在其中，系統就不會再尋找。
  3. 搜尋預設語言代碼的訊息檔案。舉例來說，如果擴充功能的「default_locale」設為「es」，且 /_locales/en_GB/messages.json 和 /_locales/en/messages.json 都不包含訊息，擴充功能就會使用 /_locales/es/messages.json 的訊息。

在下圖中，名為「colores」的訊息位於擴充功能支援的所有三個語言代碼中，但「extName」僅位於其中兩個語言代碼中。如果使用者在美國英文版 Google Chrome 中看到「Colors」標籤，英國英文版使用者就會看到「Colours」。美式英文和英式英文使用者都會看到擴充功能名稱「Hello World」。由於預設語言是西班牙文，因此在 Google Chrome 中使用任何非英文語言的使用者，都會看到「Colores」標籤和「Hola mundo」擴充功能名稱。

四個檔案：manifest.json 和三個 messages.json 檔案 (分別用於 es、en 和 en_GB)。es 和 en 檔案會顯示名為「extName」和「colores」的訊息項目；en_GB 檔案只有一個項目 (「colores」)。

設定瀏覽器的語言代碼

如要測試翻譯，建議您設定瀏覽器的語言代碼。本節說明如何在 Windows、macOS、Linux 和 ChromeOS 中設定語言代碼。

Windows

您可以使用特定語言代碼的快速鍵或 Google Chrome UI 變更語言代碼。設定完成後，捷徑方法會更快，而且可以一次使用多種語言。

使用地區專屬快速鍵

如要建立及使用捷徑，以特定語言代碼啟動 Google Chrome，請按照下列步驟操作：

  1. 複製桌面上現有的 Google Chrome 捷徑。
  2. 將新捷徑重新命名，以符合新語言代碼。

  3. 變更捷徑的屬性，讓「目標」欄位指定 --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
使用 UI

如要在 Windows 版 Google Chrome 中使用使用者介面變更語言代碼，請按照下列步驟操作：

  1. 應用程式圖示 >「選項」
  2. 選擇「Under the Hood」分頁
  3. 捲動至「網路內容」
  4. 按一下「變更字型和語言設定」。
  5. 選擇「語言」分頁標籤
  6. 使用下拉式選單設定 Google Chrome 語言
  7. 重新啟動 Chrome

Mac 作業系統

如要在 Mac 上變更語言代碼，請使用系統偏好設定。

  1. 在 Apple 選單中選擇「系統偏好設定」
  2. 在「個人」部分下方，選擇「國際」
  3. 選擇語言和地區
  4. 重新啟動 Chrome

Linux

如要在 Linux 上變更語言代碼，請先關閉 Google Chrome。接著，在同一行中設定 LANGUAGE 環境變數，並啟動 Google Chrome。例如：

LANGUAGE=es ./chrome

ChromeOS

如要在 ChromeOS 上變更語言代碼，請按照下列步驟操作：

  1. 在系統匣中選擇「設定」。
  2. 在「語言與輸入設定」部分，選擇「語言」下拉式選單。
  3. 如果畫面上未列出你的語言，請按一下「新增語言」，然後新增語言。
  4. 新增後，按一下語言旁邊的三點圖示「更多動作」選單項目，然後選擇「將 ChromeOS 的介面文字設為這種語言」。
  5. 按一下所設語言旁邊顯示的「重新啟動」按鈕，重新啟動 ChromeOS。

範例

您可以在 examples/api/i18n 目錄中找到國際化範例。如需完整範例，請參閱 examples/extensions/news。如需其他範例和查看原始碼的說明，請參閱「範例」。

getMessage()

下列程式碼會從瀏覽器取得本地化訊息，並以字串形式顯示。並將訊息中的兩個預留位置替換為「string1」和「string2」字串。

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

以下說明如何提供及使用單一字串：

  // 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-languages，並以「,」分隔每個 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 以上版本 瀏覽器。*自 Chrome 148 起

ISO 語言代碼，例如 en 或 fr。如需這個方法支援的完整語言清單，請參閱 kLanguageInfoTable。如果語言不明，系統會傳回 und，表示 CLD 無法辨識 [percentage] 的文字

類型

字串

方法

detectLanguage()

Chrome 47 以上版本 瀏覽器。*自 Chrome 148 起 
browser.i18n.detectLanguage(
  text: string,
): Promise<object>

使用 CLD 偵測所提供文字的語言。

參數

  • 文字

    字串

    要翻譯的使用者輸入字串。

傳回

  • Promise<object>

    Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

getAcceptLanguages()

browser.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

取得瀏覽器接受的語言。這與瀏覽器使用的語言代碼不同；如要取得語言代碼，請使用 i18n.getUILanguage。

傳回

  • Promise<LanguageCode[]>

    Chrome 99 以上版本 瀏覽器 (自 Chrome 148 起)

getMessage()

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

取得指定訊息的本地化字串。如果找不到訊息，這個方法會傳回空字串 ('')。如果 getMessage() 呼叫的格式不正確 (例如 messageName 不是字串，或 substitutions 陣列超過 9 個元素)，這個方法會傳回 undefined。

參數

  • messageName

    字串

    訊息名稱，如 messages.json 檔案中所指定。

  • substitutions

    任意 選填

    最多 9 個替代字串 (如果訊息需要)。

  • 選項

    物件 選填

    Chrome 79 以上版本 Chrome 148 以上版本中的 browser.*
    • escapeLt

      布林值 選填

      將翻譯中的 < 逸出為 &lt;。這項設定僅適用於訊息本身，不適用於預留位置。如果翻譯內容用於 HTML 情境，開發人員可能會想使用這個選項。Closure Templates 與 Closure Compiler 搭配使用時，會自動產生這個值。

傳回

  • 字串

    訊息已根據目前語言代碼本地化。

getUILanguage()

browser.i18n.getUILanguage(): string

取得瀏覽器的 UI 語言。這與傳回使用者偏好語言的 i18n.getAcceptLanguages 不同。

傳回

  • 字串

    瀏覽器 UI 語言代碼，例如 en-US 或 fr-FR。