# 國際化 (i18n) ## 目錄 1. [如何支持多種語言](#l10) 2. [預定義的message](#overview-predefined) 3. [語言環境](#overview-locales) 1. [已支持的語言環境](#locales-supported) 2. [擴展怎么找到字符串](#locales-usage) 3. [如何設置瀏覽器語言](#locales-testing) 4. [示例](#overview-examples) 1. [例: getMessage](#examples-getMessage) 2. [例: getAcceptLanguages](#example-accept-languages) 5. [API 介紹: chrome.i18n](#apiReference) 國際化 (i18n) 一個支持國際化的擴展能很容易被本地化，但原始不支持自動確認語言和地區。 為了國際化您的擴展,您需要把所有用戶可見字符串保存在文件名為messages.json的文件里。每當你本地化您的擴展時，您需要在_locales/localeCode下增加這個messages.json文件，lo_caleCode_ 是一個形如en代表英語的編碼。 下面是一個支持英語(en)、西班牙語(es)和韓語(ko)的國際化擴展文件層次結構圖。  ## 如何支持多種語言 假設您有一個如下圖所列文件的擴展:  為了國際化這個擴展，您需要先命名每個用戶可見的字符串，然后將它們保存在messages.json文件里。這個擴展的manifest、CSS和JavaScript代碼文件就能根據每個字符串的名字提取到他們的本地化版本。 下圖是一個國際化擴展的文件規范示意圖（它只支持英語字符串）  **重要提示:**如果一個擴展有_locales目錄，那么manifest文件必須定義"default_locale"字段內容。 國際化擴展的一些方法、規則或技巧: * 你能使用任何一種[被支持的 locales](#overview-locales). 如果您使用未支持的locale，Google Chrome會忽略它。 * 在manifest.json和CSS文件中，像下圖一樣引用一個字符串： ``` __MSG__messagename___ ``` * 在您的擴展JavaScript程序中，像下圖一樣引用一個字符串： ``` chrome.i18n.getMessage("_messagename_") ``` * 每次調用getMessage()，最多能返回9個字符串。查看[Examples: getMessage](#examples-getMessage)連接了解更多信息 * 國際化系統已經提供了一些 message, 像 @@bidi_dir 和 @@ui_locale。 查看 [Predefined messages](#overview-predefined) 連接了解全部預定義message 名稱。 * 在message.json文件里，每個用戶可用的字符串都有一個名字項，一個"message"項和一個可選的"description"項。這個名字如"extName"或"search_string"是字符串的ID, "message"是字符串在當前語言環境中的值。"description"有一些解釋信息。示例： ``` { "search_string": { "message": "hello%20world", "description": "The string we search for. Put %20 between words that go together." }, ... } ``` 了解更多信息，請查看[Formats: Locale-Specific Messages](http://code.google.com/chrome/extensions/i18n-messages.html). 一旦國際化了擴展，就很容易支持其它語言了。1、拷貝一個message.json,翻譯其字符串，然后將它保存在_locales目錄下。例如:為了支持西班牙語，只要翻譯好一個message.json，放在_locales/es目錄下。下圖展示了上述擴展在支持了西班牙語以后的文件層次圖。  ## 預定義 messages 國際化系統提供一些預定義messages來幫助您本地化擴展。這些包括@@ui_locale(您能用它檢測當前UI系統的語言信息),也包括一些以@@bidi_作前部的message(用來檢測文字方向書寫習慣，像英語的是從左到右書寫習慣)，它們(@@bidi_)有相似的名字， 例舉于:[gadgets BIDI (bi-directional) API](i18n.html#BIDI). @@extension_id message 能用在任意擴展 的CSS和JavaScript 文件中，無論其是否已經本地化，但不能用在manifest.json文件中。 **注意:**Content script CSS files 不能用一些預定義message，像 @@extension_id。更多信息參見[bug 39899](http://crbug.com/39899). 下表描述了每個預定義的message。 | Message 名字 | 描述 | | --- | --- | | @@extension_id | 這個擴展的 ID; 您可以在擴展內部用這個字符串構造URL用于訪問某些資源。 沒有本地化的擴展也可以使用這個message. **注意:** 您不能在manifest文件中使用這個message | | @@ui_locale | 當前語言; 您可以用這個字符串構造和語言環境相關的URL。 | | @@bidi_dir | 當前語言環境的文字方向, 要么是 "ltr" (代表從左到向的語言，如英語)。要么是rtl" (代表右到左的語言，如日語)。 | | @@bidi_reversed_dir | 其值是對@@bidi_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_* messages 的例子： ``` 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; ``` ## 語言環境 擴展能使用所有Google Chrome支持的語言，,附加幾個有幾種地區變化的語言(如en : en_GB代表英式英語， en_US代表美式英語)。 ### 已支持的語言 你的擴展能使用下列的任一種語言: am ar bg bn ca cs da de el en en_GB en_US es es_419 et fi fil fr gu he hi hr hu id it ja kn ko ltlv ml mr nl or pl pt pt_BR pt_PT ro ru sk sl sr sv sw ta te th tr uk vi zh zh_CN zh_TW ### 擴展怎么查找字符串 您不是必須為每個語言定義各個字符串。支持國際化的擴展自帶自動搜索功能，只要默認語言的message.json文件中字義了這些字符串，無論是什么語言，您的擴展都能運行起來。下面介紹擴展系統怎么搜索message.json： 1. 在用戶首選的存在的語言中搜索messages文件 。舉個例子：如果Google Chrome的語言設置為英式英語(en_GB),系統會先查找_locales/en_GB/messages.json，如果這個文件和其message存在，系統停止搜索。 2. 如果用戶首選的語言編碼有一個帶下劃線的地區標識碼。如:en_US。那么系統會再次搜索en(不帶US)的message文件。果這個文件和message存在，系統停止搜索。 3. 搜索擴展默認語言的messages 文件。舉例：默認語言是 "ES"，那么，搜索 _locales/es/messages.json.。 下圖中，"colores"的message有三種語言支持，"extName"有兩種。美式英語用戶始終會看到標簽"Colors"，英式英語用戶會看到標簽"Clours"，他們會同時看到標簽"Hello World"。因為默認語言是西班牙語，所以非英語用戶會看到標簽"Colores"和擴展名稱"Hola mundo"。  ### 怎么設置瀏覽器的語言 為了測試翻譯，您可能需要設置瀏覽器的語言.這部份介紹怎么在[Windows](#testing-win),[Mac OS X](#testing-mac), and [Linux](#testing-linux)上設置語言。 #### Windows 你可以在locale-specific快捷方式或Google Chrome UI上改變語言。用快捷方式建立更快，并且這種方法能同時使用多種語言。 ##### 使用locale-specific快捷方式 創建和使用快捷方式，運行特定語言的Google Chrome： 1. 復制一個Google Chrome的桌面快捷方式。 2. 用語言編碼命名新的快捷方式，如cn_chrome.lnk。 3. 選擇快捷方式的連接屬性，加入--lang和--user-data-dir參數。如： ``` _path_to_chrome.exe_ --lang=_locale_ --user-data-dir=c:_locale_profile_dir_ ``` 4. 雙擊新的快捷方式運行Chrome。 示例：用西班牙語創建此類快捷方式: ``` _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，但是正如您所見，加這個參數也很容易。并且每為個語言指定一個user-data-dir目錄，可以讓你在同一時間運行幾種語言的瀏覽器。 不過有一個缺點，因為語言數據是不共享的，所以您需要安裝多次擴展(需要為為每種語言安裝一次)。呵呵，當然你不想使用這種語言也可以不安裝。查看[Creating and Using Profiles](http://www.chromium.org/developers/creating-and-using-profiles)連接獲得更多信息。 ##### 使用 UI 怎么使用windows版本Google Chrome UI 改變語言 1. 設置按鈕（扳手圖標）->選項 2. 選擇當前標簽頁 3. 將頁面滾動到底 4. 點擊"改變字符和語言設置" 5. 選擇語言標簽 6. 使用下拉列表設置Google Chrome語言 7. 重啟Chrome #### Mac OS X 在Mac上改變語言，您需要使用系統preferences 1. 從Apple menu上選擇**System Preferences** 2. 在**Personal**部份,選擇**International** 3. 選擇你的語言和地域 4. 重啟chrome #### Linux Linux上改變語言，先退出Google Chrome，再如下設置環境變量，重啟即可: ``` LANGUAGE=es ./chrome ``` ## 一些例子 您能輕松的在[examples/api/i18n](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/i18n/)目錄下找到國際化的例子。[xamples/extensions/news](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/news/)目錄下有更完整的例子。[samples](samples.html)有代碼級的其它例子和幫助。 ### 函數 getMessage示例 下面的代碼介紹了怎么得到和顯示一個本地化的字符串。用"string1"和"string2"替換message的兩個占位符。 ``` 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); _// In messages.json_ "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." } } } ``` [Locale-Specific Messages](http://code.google.com/chrome/extensions/i18n-messages.html) 了解更多占位符的信息。關于調用函數getMessage()的更多信息參見[API reference](#method-getMessage). ### 函數getAcceptLanguages示例 下例代碼介紹了怎么取得所有可用的語言，把它們以"，"號連接成字符串并顯示。 ``` function getAcceptLanguages() { chrome.i18n.getAcceptLanguages(function(languageList) { var languages = languageList.join(","); document.getElementById("languageSpan").innerHTML = languages; }) } ``` 調用函數getAcceptLanguages()的更多細節請參見[API reference](#method-getAcceptLanguages). ## API 介紹: chrome.i18n ### 方法 #### getAcceptLanguages chrome.i18n.getAcceptLanguages(functioncallback) 取得所有的可用語言，這個和瀏覽器使用的語言不同， 用window.navigator.language.取得這瀏覽器使用的語言 #### 參數 callback_(function)_ #### callback function 這個回調參數應該是一個函數，類似于： ``` function(array of string languages) {...}; ``` languages_(array of string )_ 瀏覽器可接受的語言數組, 類似于 en-US,en,zh-CN #### getMessage string chrome.i18n.getMessage(string messageName, string or array of string substitutions) 用指定的message取得字符串。如果message不存在，此方法返回空串。如果調用格式錯誤，如_messageName_不是一個串或是_substitution_為空或大于9個元素。此函數返回"undefined" #### 參數 messageName_(string)_ message名字, 在[messages.json](http://code.google.com/chrome/extensions/i18n-messages.html)文件中使用的名字 substitutions_(optionalstring or array of string)_ 如果message需要這個參數，設定1到9個子串。 #### 返回 _(string)_ 當前語言設置的Message