Nội dung mô tả
Sử dụng cơ sở hạ tầng chrome.i18n
để triển khai quốc tế hoá trên toàn bộ ứng dụng hoặc tiện ích của bạn.
Bạn cần đặt tất cả các chuỗi mà người dùng thấy vào tệp có tên messages.json
. Mỗi lần thêm một ngôn ngữ mới, bạn sẽ thêm tệp thông báo trong thư mục có tên _locales/_localeCode_
, trong đó localeCode là một mã như en
cho tiếng Anh.
Dưới đây là hệ phân cấp tệp cho một tiện ích quốc tế hoá hỗ trợ tiếng Anh (en
), tiếng Tây Ban Nha (es
) và tiếng Hàn (ko
):
Cách hỗ trợ nhiều ngôn ngữ
Giả sử bạn có một tiện ích với các tệp như trong hình sau:
Để quốc tế hoá phần mở rộng này, bạn đặt tên cho từng chuỗi mà người dùng thấy và đưa vào một tệp tin nhắn. Tệp kê khai, tệp CSS và mã JavaScript của tiện ích sử dụng tên của từng chuỗi để lấy phiên bản đã bản địa hoá.
Dưới đây là giao diện của phần mở rộng này khi quốc tế hoá (lưu ý rằng phần mở rộng vẫn chỉ có các chuỗi tiếng Anh):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="Trong tệp manifest.json, " và ="" đã ="" đã thay đổi ="" chrome.i18n.getmessage="" extname =" hello / hình ảnh" . "
Một số lưu ý về việc quốc tế hoá:
- Bạn có thể sử dụng bất cứ ngôn ngữ được hỗ trợ nào. Nếu bạn sử dụng ngôn ngữ không được hỗ trợ, Google Chrome sẽ bỏ qua ngôn ngữ đó.
Trong các tệp
manifest.json
và CSS, hãy tham chiếu đến một chuỗi có tên messagename như sau:__MSG_messagename__
Trong mã JavaScript của tiện ích hoặc ứng dụng, hãy tham chiếu đến một chuỗi có tên messagename như sau:
chrome.i18n.getMessage("messagename")
Trong mỗi lệnh gọi đến
getMessage()
, bạn có thể cung cấp tối đa 9 chuỗi để đưa vào thông báo. Hãy xem Ví dụ: getMessage để biết thông tin chi tiết.Một số thông báo (chẳng hạn như
@@bidi_dir
và@@ui_locale
) do hệ thống quốc tế hoá cung cấp. Xem phần Thông báo tạo sẵn để biết danh sách đầy đủ các tên thông báo được xác định trước.Trong
messages.json
, mỗi chuỗi mà người dùng thấy được bao gồm một tên, một mục "tin nhắn" và một mục "mô tả" không bắt buộc. Tên là các khoá như "extName" hoặc "search_string" giúp xác định chuỗi. "Thông báo" chỉ định giá trị của chuỗi ở ngôn ngữ này. "Nội dung mô tả" không bắt buộc mang lại sự hữu ích cho người dịch, những người có thể không biết được cách sử dụng chuỗi trong phần mở rộng của bạn. Ví dụ:{ "search_string": { "message": "hello%20world", "description": "The string we search for. Put %20 between words that go together." }, ... }
Để biết thêm thông tin, hãy xem phần Định dạng: Thông báo theo ngôn ngữ.
Sau khi quốc tế hoá một tiện ích hoặc ứng dụng, việc dịch tiện ích hoặc ứng dụng đó rất đơn giản. Bạn sao chép messages.json
, dịch và đặt bản sao vào một thư mục mới trong _locales
. Ví dụ: để hỗ trợ tiếng Tây Ban Nha, bạn chỉ cần đặt bản dịch của messages.json
trong _locales/es
. Hình sau đây cho thấy tiện ích trước đó kèm theo bản dịch tiếng Tây Ban Nha mới.
Tin nhắn được xác định trước
Hệ thống quốc tế hoá cung cấp một số thông báo được xác định trước để giúp bạn bản địa hoá. Các phương thức này bao gồm @@ui_locale
để bạn có thể phát hiện ngôn ngữ giao diện người dùng hiện tại và một số thông báo @@bidi_...
cho phép bạn phát hiện hướng văn bản. Các thông báo sau có tên tương tự như hằng số trong API BIDI (hai chiều) tiện ích.
Thông báo đặc biệt @@extension_id
có thể được sử dụng trong các tệp CSS và JavaScript, bất kể tiện ích hoặc ứng dụng có được bản địa hoá hay không. Thông báo này không hoạt động trong các tệp kê khai.
Bảng sau đây mô tả từng thông báo tạo sẵn.
Tên thông báo | Nội dung mô tả |
---|---|
@@extension_id | Tiện ích hoặc mã ứng dụng; bạn có thể sử dụng chuỗi này để tạo URL cho tài nguyên bên trong tiện ích. Ngay cả các tiện ích chưa được bản địa hoá cũng có thể sử dụng thông báo này. Lưu ý: Bạn không thể sử dụng thông báo này trong tệp kê khai. |
@@ui_locale | Ngôn ngữ hiện tại; bạn có thể dùng chuỗi này để tạo URL dành riêng cho từng khu vực. |
@@bidi_dir | Hướng văn bản cho ngôn ngữ hiện tại, "ltr" cho các ngôn ngữ viết từ trái sang phải, chẳng hạn như tiếng Anh hoặc "rtl" cho các ngôn ngữ viết từ phải sang trái như tiếng Nhật. |
@@bidi_reversed_dir | Nếu @@bidi_dir là "ltr", thì đây sẽ là "rtl"; nếu không, giá trị sẽ là "ltr". |
@@bidi_start_edge | Nếu @@bidi_dir là "ltr" thì giá trị này là "left"; nếu không thì là "right" ("phải"). |
@@bidi_end_edge | Nếu @@bidi_dir là "ltr", thì đây là "right"; nếu không, giá trị sẽ là "left". |
Dưới đây là ví dụ về cách sử dụng @@extension_id
trong tệp CSS để tạo URL:
body {
background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}
Nếu mã tiện ích là abcdefghijklmnopqrstuvwxyzabcdef, thì dòng in đậm trong đoạn mã trước đó sẽ trở thành:
background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');
Dưới đây là ví dụ về cách sử dụng thông báo @@bidi_*
trong tệp CSS:
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;
}
Đối với ngôn ngữ viết từ trái sang phải, chẳng hạn như tiếng Anh, các dòng in đậm sẽ trở thành:
dir: ltr;
padding-left: 0;
padding-right: 1.5em;
Ngôn ngữ
Bạn có thể chọn trong số nhiều ngôn ngữ, bao gồm cả một số ngôn ngữ (chẳng hạn như en
), cho phép một bản dịch hỗ trợ nhiều biến thể của một ngôn ngữ (chẳng hạn như en_GB
và en_US
).
Địa phương được hỗ trợ
Bạn có thể sử dụng bất kỳ ngôn ngữ nào mà Cửa hàng Chrome trực tuyến hỗ trợ.
Tìm kiếm thư
Bạn không phải xác định từng chuỗi cho mọi ngôn ngữ được hỗ trợ. Miễn là tệp messages.json
của ngôn ngữ mặc định có giá trị cho mỗi chuỗi, tiện ích hoặc ứng dụng của bạn sẽ chạy bất kể bản dịch có thưa thớt đến mức nào. Dưới đây là cách hệ thống tiện ích tìm kiếm thông báo:
- Tìm kiếm tệp thông báo (nếu có) theo ngôn ngữ ưu tiên của người dùng. Ví dụ: trước tiên, khi ngôn ngữ của Google Chrome được đặt thành tiếng Anh Anh (
en_GB
), trước tiên, hệ thống sẽ tìm thông báo trong_locales/en_GB/messages.json
. Nếu tệp đó tồn tại và thông báo ở đó, hệ thống sẽ không tìm kiếm thêm nữa. - Nếu ngôn ngữ ưu tiên của người dùng có một khu vực (nghĩa là ngôn ngữ có dấu gạch dưới: _), hãy tìm kiếm ngôn ngữ không có khu vực đó. Ví dụ: nếu tệp thông báo
en_GB
không tồn tại hoặc không chứa thông báo, thì hệ thống sẽ xem tệp thông báoen
. Nếu tệp đó tồn tại và thông báo ở đó, hệ thống sẽ không tìm kiếm thêm nữa. - Tìm kiếm tệp thông báo cho ngôn ngữ mặc định. Ví dụ: nếu "default_locale" của tiện ích được đặt thành "es" và cả
_locales/en_GB/messages.json
và_locales/en/messages.json
đều không chứa thông báo, thì tiện ích sẽ sử dụng thông báo từ_locales/es/messages.json
.
Trong hình sau, thông báo có tên "colores" xuất hiện ở cả 3 ngôn ngữ mà tiện ích hỗ trợ, nhưng "extName" chỉ ở hai ngôn ngữ trong số đó. Bất cứ khi nào người dùng chạy Google Chrome bằng tiếng Anh Mỹ sẽ thấy nhãn "Màu", thì người dùng tiếng Anh Anh sẽ nhìn thấy "Màu sắc". Cả người dùng tiếng Anh Mỹ và tiếng Anh Anh đều thấy tên tiện ích "Hello World". Vì ngôn ngữ mặc định là tiếng Tây Ban Nha, nên người dùng chạy Google Chrome bằng bất kỳ ngôn ngữ nào không phải tiếng Anh sẽ thấy nhãn "Màu" và tên tiện ích có tên "Hola mundo".
Cách đặt ngôn ngữ cho trình duyệt
Để kiểm tra bản dịch, bạn nên đặt ngôn ngữ cho trình duyệt. Phần này hướng dẫn bạn cách đặt ngôn ngữ trong Windows, Mac OS X, Linux và ChromeOS.
Windows
Bạn có thể thay đổi ngôn ngữ bằng cách sử dụng phím tắt dành riêng cho từng ngôn ngữ hoặc giao diện người dùng của Google Chrome. Sau khi bạn thiết lập, phương pháp phím tắt này sẽ nhanh chóng hơn và cho phép bạn sử dụng nhiều ngôn ngữ cùng lúc.
Sử dụng lối tắt theo ngôn ngữ cụ thể
Cách tạo và sử dụng phím tắt giúp khởi chạy Google Chrome bằng một ngôn ngữ cụ thể:
- Tạo một bản sao lối tắt Google Chrome đã có trên màn hình của bạn.
- Đổi tên phím tắt mới cho phù hợp với ngôn ngữ mới.
Thay đổi các thuộc tính của lối tắt để trường Mục tiêu chỉ định cờ
--lang
và--user-data-dir
. Mục tiêu sẽ có dạng như sau:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
Chạy Google Chrome bằng cách nhấp đúp vào phím tắt.
Ví dụ: để tạo một lối tắt chạy Google Chrome bằng tiếng Tây Ban Nha (es
), bạn có thể tạo một lối tắt có tên chrome-es
với mục tiêu sau:
path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es
Bạn có thể tạo bao nhiêu phím tắt tuỳ thích, giúp dễ dàng thử nghiệm bằng nhiều ngôn ngữ. Ví dụ:
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
Sử dụng giao diện người dùng
Dưới đây là cách thay đổi ngôn ngữ thông qua giao diện người dùng trên Google Chrome dành cho Windows:
- Biểu tượng ứng dụng > Tuỳ chọn
- Chọn thẻ Nâng cao
- Di chuyển xuống phần Nội dung web
- Nhấp vào Thay đổi chế độ cài đặt phông chữ và ngôn ngữ
- Chọn thẻ Ngôn ngữ
- Sử dụng trình đơn thả xuống để đặt Ngôn ngữ của Google Chrome
- Khởi động lại Chrome
Mac OS X
Để thay đổi ngôn ngữ trên máy Mac, bạn cần sử dụng các lựa chọn ưu tiên về hệ thống.
- Trên trình đơn Apple, hãy chọn System Preferences (Lựa chọn ưu tiên về hệ thống)
- Trong phần Cá nhân, hãy chọn Quốc tế
- Chọn ngôn ngữ và vị trí của bạn
- Khởi động lại Chrome
Linux
Để thay đổi ngôn ngữ trên Linux, trước tiên hãy thoát Google Chrome. Sau đó, trong một dòng, hãy đặt biến môi trường LANGUAGE và chạy Google Chrome. Ví dụ:
LANGUAGE=es ./chrome
ChromeOS
Cách thay đổi ngôn ngữ trên ChromeOS:
- Trên khay hệ thống, hãy chọn Settings (Cài đặt).
- Trong phần Ngôn ngữ và nhập liệu, chọn menu thả xuống Ngôn ngữ.
- Nếu ngôn ngữ của bạn không có trong danh sách, hãy nhấp vào Thêm ngôn ngữ rồi thêm ngôn ngữ đó.
- Sau khi thêm, hãy nhấp vào mục trong trình đơn Thao tác khác có biểu tượng 3 dấu chấm bên cạnh ngôn ngữ của bạn rồi chọn Hiển thị ChromeOS bằng ngôn ngữ này.
- Nhấp vào nút Restart (Khởi động lại) xuất hiện bên cạnh ngôn ngữ đã đặt để khởi động lại ChromeOS.
Ví dụ
Bạn có thể tìm thấy các ví dụ đơn giản về quá trình quốc tế hoá trong thư mục examples/api/i18n. Để xem ví dụ đầy đủ, hãy xem examples/extensions/news. Để biết các ví dụ khác và để được trợ giúp khi xem mã nguồn, hãy xem phần Mẫu.
Ví dụ: getMessage
Mã sau đây nhận một thông báo đã bản địa hoá từ trình duyệt và hiển thị dưới dạng một chuỗi. Thao tác này thay thế 2 phần giữ chỗ trong thông báo bằng các chuỗi "string1" và "string2".
function getMessage() {
var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
document.getElementById("languageSpan").innerHTML = message;
}
Dưới đây là cách bạn cung cấp và sử dụng một chuỗi đơn:
// 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."
}
}
}
Để biết thêm thông tin về phần giữ chỗ, hãy xem trang Thông báo theo ngôn ngữ cụ thể. Để biết thông tin chi tiết về cách gọi getMessage()
, hãy xem Tài liệu tham khảo API.
Ví dụ: getAcceptLanguage
Mã sau đây nhận các ngôn ngữ chấp nhận từ trình duyệt và hiển thị các ngôn ngữ đó dưới dạng chuỗi bằng cách phân tách từng ngôn ngữ chấp nhận bằng ','.
function getAcceptLanguages() {
chrome.i18n.getAcceptLanguages(function(languageList) {
var languages = languageList.join(",");
document.getElementById("languageSpan").innerHTML = languages;
})
}
Để biết thông tin chi tiết về cách gọi getAcceptLanguages()
, hãy xem tài liệu tham khảo API.
Ví dụ: detectLanguage
Mã sau đây phát hiện tối đa 3 ngôn ngữ trong chuỗi đã cho và hiển thị kết quả dưới dạng các chuỗi được phân tách bằng các dòng mới.
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;
});
}
Để biết thêm thông tin chi tiết về cách gọi detectLanguage(inputText)
, hãy xem tài liệu tham khảo API.
Loại
LanguageCode
Mã ngôn ngữ ISO như en
hoặc fr
. Để xem danh sách đầy đủ các ngôn ngữ mà phương thức này hỗ trợ, hãy xem kLanguageInfoTable. Đối với ngôn ngữ không xác định, und
sẽ được trả về. Điều này có nghĩa là CLD không xác định được [percentage] văn bản
Loại
string
Phương thức
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
Phát hiện ngôn ngữ của văn bản đã cung cấp bằng CLD.
Tham số
-
văn bản
string
Chuỗi dữ liệu nhập của người dùng cần được dịch.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: object) => void
-
kết quả
đối tượng
Đối tượng LanguageDetectionResult chứa mảng độ tin cậy và mảng langugae được phát hiện của DiagnosticsLanguage
-
isReliable
boolean
CLD phát hiện độ tin cậy của ngôn ngữ
-
ngôn ngữ
đối tượng[]
mảng discoveryLanguage
-
language
string
-
phần trăm
number
Tỷ lệ phần trăm ngôn ngữ phát hiện được
-
-
-
Giá trị trả về
-
Promise<object>
Chrome 99 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Nhận thông tin chấp nhận ngôn ngữ của trình duyệt. Ngôn ngữ này khác với ngôn ngữ mà trình duyệt sử dụng. Để nhận ngôn ngữ, hãy sử dụng i18n.getUILanguage
.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(languages: string[]) => void
-
ngôn ngữ
chuỗi[]
Mảng mã ngôn ngữ
-
Giá trị trả về
-
Promise<LanguageCode[]>
Chrome 99 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
Lấy chuỗi đã bản địa hoá cho thông báo được chỉ định. Nếu thông báo bị thiếu, phương thức này sẽ trả về một chuỗi trống (""). Nếu định dạng của lệnh gọi getMessage()
không chính xác, ví dụ: messageName không phải là chuỗi hoặc mảng thay thế có hơn 9 phần tử — phương thức này trả về undefined
.
Tham số
-
messageName
string
Tên thông báo, như được chỉ định trong tệp
messages.json
. -
thay thế
không bắt buộc bất kỳ
Tối đa 9 chuỗi thay thế nếu thông báo yêu cầu bất kỳ chuỗi nào.
-
tùy chọn
đối tượng không bắt buộc
Chrome 79 trở lên-
escapeLt
boolean không bắt buộc
Thoát
<
trong bản dịch sang<
. Điều này chỉ áp dụng cho chính thông báo chứ không áp dụng cho phần giữ chỗ. Các nhà phát triển có thể muốn sử dụng bản dịch này nếu bản dịch được sử dụng trong ngữ cảnh HTML. Các mẫu Đóng được sử dụng với Trình biên dịch đóng sẽ tự động tạo hoạt động này.
-
Giá trị trả về
-
string
Đã bản địa hoá thông báo cho ngôn ngữ hiện tại.
getUILanguage()
chrome.i18n.getUILanguage()
Lấy ngôn ngữ giao diện người dùng của trình duyệt. Hàm này khác với i18n.getAcceptLanguages
trả về ngôn ngữ ưu tiên của người dùng.
Giá trị trả về
-
string
Mã ngôn ngữ trên giao diện người dùng của trình duyệt như en-US hoặc fr-FR.