本頁面由 Cloud Translation API 翻譯而成。

chrome.i18n

說明

使用 chrome.i18n 基礎架構，為整個應用程式或擴充功能導入國際化功能。

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

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

安裝在擴充功能目錄中：Manifest.json、*.html、*.js、_locales 目錄。在 _locales 目錄下：en、es 和 ko 目錄，每個目錄都包含 messages.json 檔案。

如何支援多種語言

假設您的擴充功能如下圖所示：

manifest.json 檔案和含有 JavaScript 的檔案。這個 .json 檔案中

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

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

重要事項：如果擴充功能有 _locales 目錄，則資訊清單必須定義 "default_locale"。

國際化注意事項：

你可以使用系統支援的任何語言代碼。如果使用不支援的語言代碼，Google Chrome 忽略該訊息
在 manifest.json 和 CSS 檔案中，參照名為 messagename 的字串，如下所示：
```
__MSG_messagename__
```
在擴充功能或應用程式的 JavaScript 程式碼中，參照名為 messagename 的字串，如下所示：
```
chrome.i18n.getMessage("messagename")
```
每次呼叫 getMessage() 時，您最多可提供 9 個字串加入訊息中。詳情請見範例：getMessage。
部分訊息 (例如 @@bidi_dir 和 @@ui_locale) 是由國際化提供有些人會將 Cloud Storage 視為檔案系統但實際上不是如需預先定義訊息名稱的完整清單，請參閱「預先定義的郵件」一節。
在 messages.json 中，每個使用者可看到的字串都有一個名稱、「訊息」和選填的 "description"項目。名稱是「extName」這類金鑰或「搜尋字串」識別字串。「訊息」指定此語言代碼中字串的值。選填的「說明」這類譯者或許就無法查看字串在。例如：
```
{
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}
```
詳情請參閱「格式：特定語言代碼訊息」。

當擴充功能或應用程式經過國際化後，就能輕鬆進行翻譯。你複製了 messages.json，翻譯指令碼，然後將副本放入 _locales 下的新目錄。例如支援西班牙文，只要在 _locales/es 下提供messages.json的翻譯版本即可。下圖顯示舊版擴充功能的新西班牙文版本

這個示例與上圖相同，但包含新檔案 (位於 _locales/es/messages.json)，其中包含訊息的西班牙文翻譯。

預先定義的訊息

國際化系統會提供幾種預先定義的訊息，協助您進行本地化。這些加入 @@ui_locale，以便偵測目前的 UI 語言代碼，以及一些 @@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」；否則為「右」
`@@bidi_end_edge`	如果 `@@bidi_dir` 為「ltr」，則為「right」；否則為「左」

以下示範如何在 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 線上應用程式商店支援的任何語言代碼。

搜尋郵件

您不必為每個支援的語言代碼定義所有字串。只要預設語言代碼的每個字串都有一個 messages.json 值，無論如何，擴充功能或應用程式都會執行「稀疏」翻譯擴充功能系統搜尋訊息的方式如下：

搜尋訊息檔案 (如果有的話)，找出使用者偏好的語言代碼。舉例來說 Chrome 的語言代碼設為英式英文 (en_GB)，系統會先在 _locales/en_GB/messages.json。如果檔案確實存在，且有訊息，系統會檢查檔案停止顯示
如果使用者偏好的語言代碼有區域 (也就是語言代碼有底線：_)，請搜尋沒有該區域的語言代碼舉例來說，如果 en_GB 訊息檔案不存在，或是未包含此訊息，系統會檢查 en 訊息檔案。如果該檔案確實存在就表示系統找不到訊息
搜尋預設語言代碼的訊息檔案。舉例來說，假設擴充功能的「default_locale」是設為「es」，且 _locales/en_GB/messages.json 或 _locales/en/messages.json 包含訊息，擴充功能會使用 _locales/es/messages.json。

在下圖中，名為「colores」的訊息都來自於上述三個語言代碼但「extName」則支援只有兩個語言代碼時使用者在美國執行 Google Chrome 時所在的位置英文顯示「Colors」標籤，英式英文使用者會看到「Colorours」。提供英文 (美國) 和英式英文使用者會看到擴充功能名稱「Hello World」。預設語言是西班牙文無論使用者是使用英文以外的語言執行 Google Chrome，都會看到「顏色」標籤和擴充功能「Hola mundo」。

四個檔案： manifest.json 和三個 messages.json 檔案 (適用於 es、en 和 en_GB)。es 和 en 檔案會顯示名為

如何設定瀏覽器的語言代碼

如要測試翻譯結果，請設定瀏覽器的語言代碼。本節將說明如何設定 Windows、Mac OS X、Linux 和 ChromeOS 的語言代碼。

Windows

您可以使用特定語言代碼的捷徑或 Google Chrome UI 變更語言代碼。快速鍵有助於加快速度，一旦設定完成，就能一次使用多種語言。

使用特定語言代碼捷徑

如何建立及使用特定語言代碼來啟動 Google Chrome：

複製桌面上現有的 Google Chrome 捷徑。
根據新的語言代碼重新命名新的捷徑。
變更捷徑的屬性，讓「Target」欄位指定 --lang 和 --user-data-dir 旗標。目標應如下所示：
```
path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
```
按兩下捷徑即可啟動 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

敬上

注意：您可以選擇是否要指定 --user-data-dir，但非常便利。為每個語言代碼設定一個資料目錄可讓您同時以多種語言執行瀏覽器。缺點是語言代碼資料不會共用，你必須多次安裝擴充功能。每個語言代碼都要安裝一次但如果你不會說這種語言，這可能會是一大挑戰詳情請參閱建立及使用設定檔。

運用使用者介面

以下說明如何在 Windows 版 Google Chrome 中，使用使用者介面變更語言代碼：

應用程式圖示 >選項
選擇「幕後設定」分頁標籤
向下捲動至「網頁內容」
按一下「變更字型和語言設定」。
選擇「語言」分頁標籤
使用下拉式選單設定 Google Chrome 語言
重新啟動 Chrome

Mac OS X

如要變更 Mac 的語言，請使用系統偏好設定。

在 Apple 選單中選擇「System Preferences」。
在「個人」部分下方，選擇「國際」。
選擇語言和地區
重新啟動 Chrome

Linux

如要變更 Linux 的語言，請先關閉 Google Chrome。然後，請在同一行設定 LANGUAGE 環境變數並啟動 Google Chrome例如：

LANGUAGE=es ./chrome

ChromeOS

如何變更 ChromeOS 的語言代碼：

在系統匣中，選擇「設定」。
在「語言與輸入法」部分中，選擇「語言」下拉式選單。
如果畫面上未列出所需語言，請按一下「新增語言」並加入所需語言。
新增完成後，按一下語言旁邊的 3 點 [更多動作] 選單項目，然後選擇 將 ChromeOS 的介面文字設為這個語言。
按一下設定語言旁邊的「重新啟動」按鈕，重新啟動 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

下列程式碼會從瀏覽器取得接受的語言，並以字串形式顯示請使用「,」分隔每個接受的語言。

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，這表示 CLD 無法得知文字的 [percentage]

類型

字串

方法

detectLanguage()

Promise Chrome 47 以上版本

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

參數

文字

字串

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

函式選用

callback 參數如下所示：
```
(result: object) => void
```
- 結果
  
  物件
  
  LanguageDetectionResult 物件會保留偵測到的語言可靠性和 DetectedLanguage 陣列
  - isReliable
    
    布林值
    
    CLD 偵測的語言是否穩定
  - 語言
    
    object[]
    
    偵測語言陣列
    
    language
    
    字串
    
    百分比
    
    數字
    
    偵測語言的百分比

傳回

Promise<object>

Chrome 99 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAcceptLanguages()

Promise

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

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

參數

回呼

函式選用

callback 參數如下所示：
```
(languages: string[]) => void
```
- 語言
  
  string[]
  
  LanguageCode 陣列

傳回

Promise<LanguageCode[]>

Chrome 99 以上版本

Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getMessage()

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

取得指定訊息的本地化字串。如果郵件遺失，這個方法會傳回空字串 ('')。如果 getMessage() 呼叫的格式錯誤 (例如 messageName 不是字串，或 substitutions 陣列包含超過 9 個元素)，這個方法會傳回 undefined。

參數

messageName

字串

訊息的名稱，即 messages.json 檔案中指定的名稱。
substitutions

任何選用

最多 9 個替換字串 (如果訊息需要任何的話)。
選項

物件 optional

Chrome 79 以上版本
- escapeLt
  
  布林值選填
  
  正確翻譯為<，請遠離<。這項設定僅適用於訊息本身，不適用於預留位置。如果翻譯是 HTML 環境中的，開發人員可能會採用這種做法。與 Closure Compiler 搭配使用的 Closure Template 會自動產生。

傳回

字串

目前語言代碼的本地化訊息。

getUILanguage()

chrome.i18n.getUILanguage()

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

傳回

字串

瀏覽器使用者介面的語言代碼，例如 en-US 或 fr-FR。