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

chrome.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」變更為 chrome.i18n.getMessage('extName')。名為 /_locales/en/messages.json 的新檔案會定義「extName」。

國際化功能的注意事項：

您可以使用任何支援的語言代碼。如果您使用不支援的語言代碼，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」會指定此語言代碼的字串值。選用的「說明」可協助翻譯人員，因為他們可能無法查看字串在擴充功能中的用法。例如：
```
{
  "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，可讓您偵測目前的 UI 語言代碼，以及幾則 @@bidi_... 訊息，可讓您偵測文字方向。後者訊息的名稱與 gadgets BIDI (雙向) API 中的常數相似。

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

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

訊息名稱	說明
`@@extension_id`	擴充功能或應用程式 ID；您可以使用這個字串，建構擴充功能內資源的網址。即使是未經本地化的擴充功能也可以使用這則訊息。注意：您無法在資訊清單檔案中使用這則訊息。
`@@ui_locale`	目前的語言代碼；您可以使用這個字串建構地區專屬的網址。
`@@bidi_dir`	目前語言代碼的文字方向，如果是從左到右的語言 (例如英文)，則為「ltr」；如果是從右到左的語言 (例如阿拉伯文)，則為「rtl」。
`@@bidi_reversed_dir`	如果 `@@bidi_dir` 是「ltr」，則為「rtl」；否則為「ltr」。
`@@bidi_start_edge`	如果 `@@bidi_dir` 是「ltr」，則為「左」；否則為「右」。
`@@bidi_end_edge`	如果 `@@bidi_dir` 是「ltr」，則為「右」；否則為「左」。

以下範例說明如何在 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	古吉拉特文
他	希伯來文
hi	北印度文
時	克羅埃西亞文
hu	匈牙利文
id	印尼文
it	義大利文
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 檔案為每個字串提供值，擴充功能或應用程式就會執行，無論翻譯內容有多稀疏。以下是擴充功能系統搜尋訊息的方式：

搜尋使用者偏好的語言代碼 (如有) 的訊息檔案。舉例來說，如果 Google 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」標籤，而使用英國英語的使用者則會看到「Colours」。美國英文和英國英文使用者都會看到擴充功能名稱「Hello World」。由於預設語言為西班牙文，因此使用非英語語言執行 Google Chrome 的使用者會看到「Colores」標籤和「Hola mundo」擴充功能名稱。

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

設定瀏覽器的語言代碼

如要測試翻譯內容，您可能需要設定瀏覽器的語言代碼。本節說明如何在 Windows、Mac OS、Linux 和 ChromeOS 中設定語言代碼。

Windows

您可以使用語言代碼專屬的快速鍵或 Google Chrome UI 變更語言代碼。捷徑方法設定完成後，可讓你一次使用多種語言，因此速度更快。

使用地區專屬的捷徑

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

複製電腦上現有的 Google Chrome 捷徑。
重新命名新捷徑，以符合新的語言代碼。
變更捷徑的屬性，讓「目標」欄位指定 --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 並非必要，但方便您使用。每個語言代碼都有一個資料目錄，可讓您同時以多種語言執行瀏覽器。缺點是，由於系統不會共用語言代碼的資料，因此您必須多次安裝擴充功能 (每個語言代碼一次)，如果您不熟悉該語言，這可能會造成困擾。詳情請參閱「建立及使用設定檔」一文。

使用 UI

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

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

Mac 作業系統

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

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

Linux

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

LANGUAGE=es ./chrome

ChromeOS

如要變更 ChromeOS 上的語言代碼：

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

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

類型

字串

方法

detectLanguage()

Promise Chrome 47 以上版本

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

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

參數

文字

字串

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

函式選填

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

傳回

Promise<object>

Chrome 99 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getAcceptLanguages()

Promise

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

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

參數

回呼

函式選填

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

傳回

Promise<LanguageCode[]>

Chrome 99 以上版本

承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getMessage()

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

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

參數

messageName

字串

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

任何選填

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

物件選填

Chrome 79 以上版本
- escapeLt
  
  boolean 選填
  
  將翻譯中的 < 轉換為 <。這項設定僅適用於訊息本身，不適用於預留位置。如果翻譯內容是在 HTML 情境中使用，開發人員可能會想使用這個選項。使用 Closure Compiler 的 Closure 範本會自動產生這個值。

傳回

字串

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

getUILanguage()

chrome.i18n.getUILanguage()

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

傳回

字串

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