chrome.i18n

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 được vào một tệp có tên messages.json. Mỗi lần bạn thêm ngôn ngữ mới, hãy thêm tệp thông báo trong thư mục có tên _locales/_localeCode_, trong đó localeCode là một mã chẳng hạn như en cho tiếng Anh.

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

Trong thư mục tiện ích: manifest.json, thư mục *.html, *.js, _locales. Trong thư mục _locales: các thư mục en, es và ko, mỗi thư mục có một tệp messages.json.

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:

Một tệp manifest.json và một tệp JavaScript. Tệp .json có

Để 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 rồi đưa chuỗi đó vào một thông báo . 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 tên phiên bản được bản địa hoá.

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

<img "__msg_extname__",="" "default_locale"="" "vi".="" "extname"."="" "xin chào="" _locales=&quot;&quot; a=&quot;&quot; alt="Trong tệp manifest.json, " and=&quot;&quot; là="" changed=&quot;&quot; chrome.i18n.getmessage("extname").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; mới="" src=&quot;/static/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; giá trị="" thế giới"="" >

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 ngôn ngữ không được hỗ trợ, Google Chrome sẽ bỏ qua nó.

  • Trong 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 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. Xem Ví dụ: getMessage để biết chi tiết.

  • Một số thông báo, chẳng hạn như @@bidi_dir và @@ui_locale, là do quốc tế hoá cung cấp hệ thống. Hãy xem phần Thông báo được xác định trước để 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 sẽ có một tên là một "thông báo" và một mục không bắt buộc &quot;description&quot; mục. Tên là một khoá, chẳng hạn như "extName" hoặc "search_string" giúp xác định . "Thông báo" chỉ định giá trị của chuỗi bằng ngôn ngữ này. "Nội dung mô tả" không bắt buộc sẽ trợ giúp cho người dịch, những người không thể hiểu được cách chuỗi được sử dụng trong tiện ích. 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ữ cụ thể.

Sau khi một tiện ích hoặc ứng dụng được quốc tế hóa, 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 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, chỉ cần đặt một bản dịch của messages.json bên dưới _locales/es. Hình sau đây hiển thị tiện ích trước cùng với bản dịch tiếng Tây Ban Nha mới.

Hình này giống với hình trước, nhưng với một tệp mới tại _locales/es/messages.json chứa bản dịch thông báo bằng tiếng Tây Ban Nha.

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 định sẵn để giúp bạn bản địa hoá. Các bao gồm @@ui_locale để bạn có thể phát hiện ngôn ngữ hiện tại của giao diện người dùng 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 điệp sau có tên tương tự như hằng số trong API tiện ích BIDI (hai chiều).

Có thể sử dụng thông báo đặc biệt @@extension_id trong tệp CSS và JavaScript, cho dù tiện ích hoặc ứng dụng được bản địa hóa. 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.

Tên thông báoMô tả
@@extension_idTiện ích hoặc mã ứng dụng; bạn có thể sử dụng chuỗi này để tạo URL cho các tài nguyên bên trong tiện ích. Ngay 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_localeNgôn ngữ hiện tại; bạn có thể sử dụng chuỗi này để tạo URL dành riêng cho từng ngôn ngữ.
@@bidi_dirHướng văn bản của ngôn ngữ hiện tại, có thể là "ltr" cho ngôn ngữ viết từ trái sang phải 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_dirNếu @@bidi_dir là "ltr", thì đây là "rtl"; nếu không thì là "ltr".
@@bidi_start_edgeNếu @@bidi_dir là "ltr", thì giá trị này là "left"; nếu không thì "đúng".
@@bidi_end_edgeNếu @@bidi_dir là "ltr", thì giá trị này là "right"; nếu không thì "bên trái".

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 mã trước đó đoạn mã 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 các ngôn ngữ từ trái sang phải như tiếng Anh, các dòng in đậm 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ữ, trong đó có một số ngôn ngữ (chẳng hạn như en) cho phép dịch một bản 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 mọi chuỗi cho mọi ngôn ngữ được hỗ trợ. Miễn là Tệp messages.json có một giá trị cho mọi chuỗi, do đó, tiện ích hoặc ứng dụng của bạn sẽ chạy bất kể cách thức bản dịch thưa thớt. Dưới đây là cách hệ thống tiện ích tìm kiếm thư:

  1. 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ụ: khi Google Ngôn ngữ của Chrome được đặt thành tiếng Anh (en_GB), trước tiên, hệ thống sẽ tìm thông báo bằng _locales/en_GB/messages.json Nếu tệp đó tồn tại và thông báo xuất hiện ở đó, hệ thống sẽ tìm chỉ một chút.
  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ữ 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 tin nhắn en. Nếu tệp đó tồn tại và thông báo vẫn tồn tại, hệ thống không cần phải kiểm tra thêm nữa.
  3. Tìm kiếm tệp thông báo theo ngôn ngữ mặc định. Ví dụ: nếu tiện ích "default_locale" được đặt thành "es" và không phải là _locales/en_GB/messages.json hoặc _locales/en/messages.json chứa tin nhắn, tiện ích sử dụng tin nhắn từ _locales/es/messages.json.

Trong hình sau, thông báo có tên "colores" (màu sắc) bằng cả ba ngôn ngữ mà tiện ích hỗ trợ, nhưng "extName" chỉ bằng hai trong số các ngôn ngữ. Bất cứ nơi nào người dùng chạy Google Chrome tại Hoa Kỳ Người dùng nói tiếng Anh sẽ thấy nhãn "Màu sắc", thì người dùng nói tiếng Anh sẽ thấy nhãn "Màu sắc". Cả tiếng Anh (Mỹ) và Người dùng tiếng Anh (Anh) sẽ thấy tên tiện ích "Hello World". Vì ngôn ngữ mặc định là tiếng Tây Ban Nha, 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 sắc" và tiện ích tên "Hola mundo".

4 tệp: manifest.json và ba tệp messages.json (đối với es, en và en_GB). Tệp es và en hiển thị các mục nhập cho các thư có tên

Cách đặt ngôn ngữ của trình duyệt

Để kiểm tra bản dịch, bạn nên đặt ngôn ngữ của trình duyệt. Phần này cho bạn biết 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 Google Chrome. Chiến lược phát hành đĩa đơn cách sử dụng phím tắt 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 lúc.

Sử dụng phím tắt dành riêng cho từng ngôn ngữ

Để tạo và sử dụng lối tắt 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àn hình của bạn.
  2. Đổi tên phím tắt mới để khớ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 Đích chỉ định --lang và Cờ --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. Khởi chạy Google Chrome bằng cách nhấp đúp vào phím tắt.

Ví dụ: để tạo 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 có 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 bạn 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

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

  1. Biểu tượng ứng dụng > Lựa chọn
  2. Chọn thẻ Nâng cao
  3. Di chuyển xuống phần Nội dung web
  4. Nhấp vào Thay đổi chế độ cài đặt phông chữ và ngôn ngữ
  5. Chọn thẻ Language (Ngôn ngữ)
  6. Sử dụng trình đơn thả xuống để đặt ngôn ngữ trong Google Chrome
  7. Khởi động lại Chrome

Mac OS X

Để thay đổi ngôn ngữ trên máy Mac, bạn hãy sử dụng chế độ ưu tiên hệ thống.

  1. Trên trình đơn Apple, hãy chọn System Preferences (Lựa chọn ưu tiên về 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 khỏi Google Chrome. Sau đó, tất cả trên cùng một dòng, đặt LANGUAGE biến môi trường 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 Settings (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 chưa 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 trong trình đơn có biểu tượng 3 dấu chấm Thao tác khác 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ụ đơn giản về quốc tế hoá trong thư mục examples/api/i18n. Đối với ví dụ đầy đủ, hãy xem ví dụ/extensions/news. Để có 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ị thông báo đó dưới dạng một chuỗi. Nó thay thế hai phần giữ chỗ trong thông báo bằng 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 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 dành riêng cho ngôn ngữ. Để biết thông tin chi tiết về gọi getMessage(), hãy xem tài liệu tham khảo API.

Ví dụ: getAcceptLanguages

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 một chuỗi bằng 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ụ: detectedLanguage

Đ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ả như sau 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 về cách gọi detectLanguage(inputText), hãy xem tài liệu tham khảo API.

Loại

LanguageCode

Chrome 47 trở lên

Mã ngôn ngữ ISO như en hoặc fr. Để biết danh sách đầy đủ các ngôn ngữ được 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ề, nghĩa là CLD không xác định được [percentage] văn bản

Loại

string

Phương thức

detectLanguage()

Lời hứa Chrome 47 trở lên 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Phát hiện ngôn ngữ của văn bản được cung cấp bằng CLD.

Tham số

  • văn bản

    string

    Chuỗi thông tin do người dùng nhập vào 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 độ tin cậy của langugae và mảng lưới Được phát hiện

      • isReliable

        boolean

        Độ tin cậy về ngôn ngữ phát hiện được CLD

      • ngôn ngữ

        object[]

        mảng phát hiện ngôn ngữ

        • language

          string

        • phần trăm

          số

          Tỷ lệ phần trăm ngôn ngữ được phát hiện

Giá trị trả về

  • Promise&lt;object&gt;

    Chrome 99 trở lên

    Lờ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()

Lời hứa 
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

Lấy các ngôn ngữ được chấp nhận 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; để lấy 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 LanguageCode

Giá trị trả về

  • Promise&lt;LanguageCode[]&gt;

    Chrome 99 trở lên

    Lờ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à một chuỗi hoặc mảng thay thế có nhiều hơn 9 phần tử – phương thức này sẽ trả về undefined.

Tham số

  • messageName

    string

    Tên thông báo, như được chỉ định trong tệp messages.json.

  • ký tự thay thế

    bất kỳ không bắt buộc

    Tối đa 9 chuỗi thay thế, nếu thông báo yêu cầu có.

  • 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 < khi dịch sang &lt;. Đ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ỗ. 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. Mẫu đóng được dùng với Trình biên dịch đóng sẽ tự động tạo đoạn mã 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ữ giao diện người dùng của trình duyệt, chẳng hạn như en-US hoặc fr-FR.