說明
使用 chrome.i18n
基礎架構,為整個應用程式或擴充功能實現國際化。
資訊清單
如果擴充功能含有 /_locales
目錄,資訊清單必須定義 "default_locale"
。
概念和用法
您需要將其使用者可見的所有字串都放入名為 messages.json
的檔案中。每次新增語言代碼時,都會在名為 /_locales/_localeCode_
的目錄下新增訊息檔案,其中 localeCode 就是一個代碼,例如 en
代表英文。
以下是支援英文 (en
)、西班牙文 (es
) 和韓文 (ko
) 的國際化擴充功能的檔案階層:
支援多種語言
假設您有一個副檔名,檔案如下圖所示:
如要國際化這個擴充功能,您可以為每個向使用者顯示的字串命名,並放入訊息檔案中。擴充功能的資訊清單、CSS 檔案和 JavaScript 程式碼會使用每個字串的名稱取得本地化版本。
以下是國際化的擴充功能外觀 (請注意,它仍然只有英文字串):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="在 manifest.json 檔案, " and="" has="" changed="" chrome.i18n.get("message="android.i18n.get("message="android-8" src1"在
國際化的相關注意事項:
- 您可以使用任何支援的語言代碼。如果使用不支援的語言代碼,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
,然後將副本放入 /_locates
下的新目錄中。舉例來說,如要支援西班牙文,只要將 messages.json
的翻譯副本放在 /_locates/es
下方即可。下圖顯示了上一個擴充內容西班牙文翻譯的擴充功能。
預先定義的訊息
國際化系統會提供一些預先定義的訊息,協助您進行本地化。其中包括 @@ui_locale
,以便偵測目前的 UI 語言代碼,以及一些用於偵測文字方向的 @@bidi_...
訊息。後者訊息的名稱與小工具 BIDI (雙向) API 中的常數相似。
CSS 和 JavaScript 檔案中可以使用特殊訊息 @@extension_id
,無論擴充功能或應用程式是否已進行本地化。這則訊息不適用於資訊清單檔案。
下表說明每個預先定義的訊息。
訊息名稱 | 說明 |
---|---|
@@extension_id | 擴充功能或應用程式 ID;您可以使用這個字串建構擴充功能中資源的網址。即使是未本地化的擴充功能也可以使用這則訊息。 注意:您無法在資訊清單檔案中使用這則訊息。 |
@@ui_locale | 目前的語言代碼;您可以使用這個字串建構地區專屬網址。 |
@@bidi_dir | 目前語言代碼的文字方向,為由左到右的語言 (例如英文),設為「ltr」,或代表由右至左的語言 (例如日文)。 |
@@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 | 古吉拉特文 |
he | 希伯來文 |
hi | 北印度文 |
時 | 克羅埃西亞文 |
hu | 匈牙利文 |
id | 印尼文 |
it | 義大利文 |
ja | 日文 |
kn | 卡納達文 |
ko | 韓文 |
lt | 立陶宛文 |
lv | 拉脫維亞文 |
ml | 馬拉雅拉姆文 |
mr | 馬拉地文 |
毫秒 | 馬來文 |
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
檔案為每個字串提供值,無論翻譯方式如何,擴充功能或應用程式就會執行。以下為擴充功能系統搜尋訊息的方式:
- 搜尋使用者偏好地區的訊息檔案 (如果有的話)。舉例來說,當 Google Chrome 的語言代碼設為英式英文 (
en_GB
) 時,系統會先在/_locates/en_GB/messages.json
中尋找訊息,如果該檔案存在,且訊息中,系統就不會再顯示檔案。 - 如果使用者偏好的語言代碼含有區域 (也就是該語言代碼會有底線:_),請搜尋不含該地區的地區。舉例來說,如果
en_GB
訊息檔案不存在或未包含訊息,系統就會查看en
訊息檔案。如果該檔案存在,且訊息中,系統不會再顯示檔案。 - 搜尋預設語言代碼的訊息檔案。舉例來說,如果擴充功能的「default_locale」設為「es」,且
/_locates/en_GB/messages.json
和/_locates/en/messages.json
皆不包含訊息,則擴充功能會使用/_locates/es/messages.json
傳送的訊息。
在下圖中,名為「colores」的訊息位於擴充功能支援的全部三個語言代碼中,但「extName」僅位於兩個語言代碼中。如果使用者在美式英文中執行 Google Chrome 時看到「Colors」標籤,英國英文使用者則會看到「Colours」標籤。英文 (美國) 和英國英文使用者會看到擴充功能名稱「Hello World」。由於預設語言為西班牙文,因此任何非英文使用者執行 Google Chrome 時,都會看到「Colores」標籤和「Hola mundo」擴充功能名稱。
設定瀏覽器的語言代碼
如要測試翻譯,建議您設定瀏覽器的語言代碼。本節將說明如何在 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
使用 UI
以下說明如何在 Google Chrome Windows 版中透過使用者介面變更語言代碼:
- 應用程式圖示 >「選項」
- 選擇「進階選項」分頁
- 向下捲動至「網頁內容」
- 按一下「變更字型及語言設定」。
- 選擇「語言」分頁標籤
- 使用下拉式選單設定 Google Chrome 語言
- 重新啟動 Chrome
Mac OS X
如要變更 Mac 的語言代碼,請使用系統偏好設定。
- 在 Apple 選單中選擇「系統偏好設定」。
- 在「個人」部分中,選擇「國際」
- 選擇語言和位置
- 重新啟動 Chrome
Linux
如要變更 Linux 的語言代碼,請先關閉 Google Chrome。接著,請在一行中設定 LANGUAGE 環境變數,並啟動 Google Chrome。例如:
LANGUAGE=es ./chrome
ChromeOS
如何變更 ChromeOS 的語言代碼:
- 在系統匣中選擇「設定」。
- 在「語言與輸入設定」部分中,選擇「語言」下拉式選單。
- 如果畫面上未列出您的語言,請按一下「新增語言」並新增。
- 新增後,按一下您語言旁邊的三點「更多動作」選單項目,然後選擇「以這個語言顯示 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
ISO 語言代碼,例如 en
或 fr
。如需此方法支援的完整語言清單,請參閱 kLanguageInfoTable。如為不明語言,系統會傳回 und
,表示 CLD 無法辨識 [percentage] 的文字
類型
字串
方法
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
使用 CLD 偵測所提供文字的語言。
參數
-
text
字串
要翻譯的使用者輸入字串。
-
回呼
函式選用
callback
參數如下所示:(result: object)=>void
-
結果
物件
保留偵測到語言穩定性和 DetectedLanguage 陣列的 LanguageDetectionResult 物件
-
isReliable
boolean
CLD 偵測到的語言穩定性
-
語言
物件 []
偵測到的語言陣列
-
language
字串
-
百分比
號碼
偵測到的語言百分比
-
-
-
傳回
-
Promise<object>
Chrome 99 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
取得瀏覽器接受的語言。與瀏覽器使用的語言不同;如要取得語言代碼,請使用 i18n.getUILanguage
。
參數
-
回呼
函式選用
callback
參數如下所示:(languages: string[])=>void
-
語言
string[]
LanguageCode 陣列
-
傳回
-
Promise<LanguageCode[]>
Chrome 99 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
取得指定訊息的本地化字串。如果訊息遺失,這個方法會傳回空白字串 (')。如果 getMessage()
呼叫的格式有誤 (例如 messageName 不是字串,或 substitutions 陣列含有超過 9 個元素),這個方法會傳回 undefined
。
參數
-
messageName
字串
訊息名稱,如
messages.json
檔案中指定的名稱。 -
substitutions
任何選填
如果訊息需要替換字串,最多 9 個。
-
選項
物件選用
Chrome 79 以上版本-
escapeLt
布林值 (選用)
將
<
翻譯成<
。這僅適用於訊息本身,不適用於預留位置。如果翻譯內容是在 HTML 內容中,開發人員就適合採用這個選項。這會自動產生與 Closure Compiler 搭配使用的 Closure Templates。
-
傳回
-
字串
訊息已根據目前語言代碼完成本地化。
getUILanguage()
chrome.i18n.getUILanguage()
取得瀏覽器的瀏覽器使用者介面語言。這與 i18n.getAcceptLanguages
不同,後者會傳回偏好使用者語言。
傳回
-
字串
瀏覽器使用者介面語言代碼,例如 en-US 或 fr-FR。