chrome.i18n

Mô tả

Tệp kê khai

Nếu tiện ích có thư mục /_locales, thì manifest phải xác định "default_locale".

Khái niệm và cách sử dụng

Bạn cần đặt tất cả các chuỗi mà người dùng nhìn thấy vào một tệp có tên là messages.json. Mỗi khi thêm một ngôn ngữ mới, bạn sẽ thêm một tệp thông báo vào thư mục có tên /_locales/_localeCode_, trong đó localeCode là một mã như en cho tiếng Anh.

Sau đây là hệ thống phân cấp tệp cho một tiện ích được quốc tế hoá, hỗ trợ tiếng Anh (en), tiếng Tây Ban Nha (es) và tiếng Hàn (ko):

Hỗ trợ nhiều ngôn ngữ

Giả sử bạn có một tiện ích có các tệp như trong hình sau:

Để quốc tế hoá tiện ích này, bạn đặt tên cho từng chuỗi mà người dùng nhìn thấy và đưa chuỗi đó vào một tệp messages. 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á của chuỗi đó.

Sau đây là giao diện của tiện ích khi được quốc tế hoá (xin lưu ý rằng tiện ích này vẫn chỉ có các chuỗi tiếng Anh):

Một số lưu ý về việc quốc tế hoá:

• Bạn có thể sử dụng bất kỳ ngôn ngữ được hỗ trợ nào. Nếu bạn sử dụng một ngôn ngữ không được hỗ trợ, Google Chrome sẽ bỏ qua ngôn ngữ đó.

• Trong tệp manifest.json và CSS, hãy tham chiếu đến một chuỗi có tên là 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 là 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. Hãy xem phần Tin nhắn được xác định trước để biết danh sách đầy đủ các tên tin nhắn được xác định trước.

• Trong messages.json, mỗi chuỗi mà người dùng nhìn thấy đều có một tên, một mục "message" và một mục "description" không bắt buộc. Tên là một khoá, chẳng hạn như "extName" hoặc "search_string", dùng để xác định chuỗi. "message" chỉ định giá trị của chuỗi trong ngôn ngữ này. "Nội dung mô tả" (không bắt buộc) giúp ích cho người dịch, vì họ có thể không thấy cách chuỗi được dùng trong tiện ích 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 được quốc tế hoá, việc dịch tiện ích trở nên đơn giản. Bạn sao chép messages.json, dịch tệp đó 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 sao đã dịch của messages.json trong /_locales/es. Hình sau đây cho thấy tiện ích trước đó có 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 thông báo này bao gồm @@ui_locale, vì vậy 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 vài 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ư các hằng số trong API BIDI (hai chiều) của tiện ích.

Bạn có thể sử dụng thông báo đặc biệt @@extension_id 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 tệp kê khai.

Bảng sau đây mô tả từng thông báo được xác định trước.

Sau đây là ví dụ về cách sử dụng @@extension_id trong tệp CSS để tạo một URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Nếu mã nhận dạng 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 những ngôn ngữ viết từ trái sang phải như tiếng Anh, các dòng chữ 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ữ địa phươ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 duy nhất hỗ trợ nhiều biến thể của một ngôn ngữ (chẳng hạn như en_GB và en_US).

Bạn có thể bản địa hoá tiện ích của mình sang bất kỳ ngôn ngữ nào mà Cửa hàng Chrome trực tuyến hỗ trợ. Nếu ngôn ngữ của bạn không có trong danh sách này, hãy chọn ngôn ngữ thay thế gần nhất. Ví dụ: nếu ngôn ngữ mặc định của tiện ích là "de_CH", hãy chọn "de" trong Cửa hàng Chrome trực tuyến.

Tìm kiếm thư

Bạn không cần xác định mọi 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 thưa thớt đến mức nào. Sau đây là cách hệ thống tiện ích tìm kiếm một thông báo:

1. Tìm ngôn ngữ ưu tiên của người dùng trong tệp thông báo (nếu có). Ví dụ: khi ngôn ngữ của Google Chrome được đặt thành tiếng Anh (Anh) (en_GB), hệ thống sẽ tìm thông báo trong /_locales/en_GB/messages.json trước. Nếu tệp đó tồn tại và thông báo có trong tệp, hệ thống sẽ không tìm kiếm thêm.
2. Nếu ngôn ngữ ưu tiên của người dùng có một khu vực (tức là ngôn ngữ có dấu gạch dưới: _), hãy tìm kiếm ngôn ngữ mà 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, hệ thống sẽ tìm trong tệp thông báo en. Nếu tệp đó tồn tại và thông báo có trong đó, thì hệ thống sẽ không tìm kiếm thêm.
3. Tìm ngôn ngữ mặc định trong tệp thông báo. Ví dụ: nếu "default_locale" của tiện ích được đặt thành "es" và cả /_locales/en_GB/messages.json lẫn /_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" nằm trong cả 3 ngôn ngữ mà tiện ích hỗ trợ, nhưng "extName" chỉ nằm trong 2 ngôn ngữ. Bất cứ khi nào người dùng chạy Google Chrome bằng tiếng Anh (Hoa Kỳ) nhìn thấy nhãn "Màu sắc", thì người dùng tiếng Anh (Anh) sẽ nhìn thấy nhãn "Màu". Cả người dùng tiếng Anh của Hoa Kỳ và tiếng Anh của Vương quốc 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 những 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 "Colores" và tên tiện ích "Hola mundo".

Đặt ngôn ngữ của trình duyệt

Để kiểm thử bản dịch, bạn nên đặt ngôn ngữ của trình duyệt. Phần này hướng dẫn bạn cách đặt ngôn ngữ trong Windows, Mac OS, Linux và ChromeOS.

Windows

Bạn có thể thay đổi ngôn ngữ bằng cách sử dụng một phím tắt dành riêng cho ngôn ngữ hoặc giao diện người dùng của Google Chrome. Phương pháp sử dụng lối tắt sẽ nhanh hơn sau khi bạn thiết lập và cho phép bạn sử dụng nhiều ngôn ngữ cùng một lúc.

Sử dụng phím tắt theo ngôn ngữ

Cách tạo và sử dụng lối tắt để khởi chạy Google Chrome bằng một ngôn ngữ cụ thể:

1. Tạo bản sao của lối tắt Google Chrome đã có trên máy tính.
2. Đổi tên lối tắt mới cho phù hợp với ngôn ngữ mới.

3. Thay đổi các thuộc tính của lối tắt để trường Target (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
   

4. Chạy Google Chrome bằng cách nhấp đúp vào lối tắt.

Ví dụ: để tạo một lối tắt khởi 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 là 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 lối tắt tuỳ thích, giúp việc kiểm thử bằng nhiều ngôn ngữ trở nên đơn giản. 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

Sau đây là cách thay đổi ngôn ngữ bằng giao diện người dùng trên Google Chrome cho Windows:

1. Biểu tượng ứng dụng > Tuỳ chọn
2. Chọn thẻ Under the Hood (Bên dưới nắp)
3. Di chuyển đến mục Nội dung trên web
4. Nhấp vào Thay đổi chế độ cài đặt phông chữ và ngôn ngữ
5. Chọn thẻ Ngôn ngữ
6. Sử dụng trình đơn thả xuống để đặt ngôn ngữ của Google Chrome
7. Khởi động lại Chrome

Mac OS

Để thay đổi ngôn ngữ trên máy Mac, bạn có thể dùng phần tuỳ chọn hệ thống.

1. Trong trình đơn Apple, hãy chọn System Preferences (Tuỳ chọn hệ thống)
2. Trong phần Cá nhân, hãy chọn Quốc tế
3. Chọn ngôn ngữ và vị trí của bạn
4. 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 đó, trên cùng một dòng, hãy đặt biến môi trường LANGUAGE và khởi chạy Google Chrome. Ví dụ:

LANGUAGE=es ./chrome

ChromeOS

Cách thay đổi ngôn ngữ trên ChromeOS:

1. Trong khay hệ thống, hãy chọn Cài đặt.
2. Trong phần Ngôn ngữ và phương thức nhập, hãy chọn trình đơn thả xuống Ngôn ngữ.
3. 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ữ đó.
4. Sau khi thêm, hãy nhấp vào mục trình đơn Thao tác khá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.
5. Nhấp vào nút 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ụ về việc quốc tế hoá trong thư mục examples/api/i18n. Để xem ví dụ đầy đủ, hãy xem examples/extensions/news. Để xem các ví dụ khác và được trợ giúp xem mã nguồn, hãy xem phần Mẫu.

getMessage()

Mã sau đây lấy một thông báo đã bản địa hoá từ trình duyệt và hiển thị thông báo đó dưới dạng một chuỗi. Hàm 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 duy nhất:

  // 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ữ. Để biết thông tin chi tiết về cách gọi getMessage(), hãy xem tài liệu tham khảo về API.

getAcceptLanguages()

Đoạn mã sau đây lấy các ngôn ngữ được chấp nhận từ trình duyệt và hiển thị các ngôn ngữ đó dưới dạng một chuỗi bằng cách phân tách từng ngôn ngữ được chấp nhận bằng dấu ",".

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 về API.

detectLanguage()

Đoạn mã sau đây phát hiện tối đa 3 ngôn ngữ từ 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 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 về API.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
): Promise<object>

chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string