directory

  1. How to support multiple languages

  2. Predefined messages

  3. The language environment

    1. Supported locale
    2. How does the extension find the string
    3. How do I set the browser language

  4. The sample

    1. Example: the getMessage
    2. Example: getAcceptLanguages

  5. Chrome. I18n

Internationalization (i18n)

An extension that supports internationalization can be easily localized, but the original does not support automatic validation of languages and locales.

To internationalize your extension, you need to save all user-visible strings in a file named messages.json. Whenever you localize your extension, you need to add this messages.json file under locales/localeCode, where lo_caleCode is a code shaped like en for English.

The following is a hierarchy diagram of an internationalized extension file that supports English (EN), Spanish (ES), and Korean (KO).

How to support multiple languages

Suppose you have an extension to the file listed below:

To internationalize the extension, you need to name the strings visible to each user and then save them in a messages.json file. The extension’s manifest, CSS, and JavaScript code files extract localized versions of each string based on its name.

The following is a diagram of the file specification for an internationalized extension (it only supports English strings)

Important: If an extension has a _locales directory, the manifest file must define the contents of the “default_locale” field.

Some methods, rules, or techniques for internationalizing extensions:

  • You can use any of the supported locales. If you use an unsupported locale, Google Chrome ignores it.

  • In the manifest.json and CSS files, reference a string as shown below:

    __MSG__messagename___
Copy the code

  • In your extended JavaScript program, reference a string as shown below:

    chrome.i18n.getMessage("_messagename_")
Copy the code

  • Each call to getMessage() returns a maximum of nine strings. See the Examples: getMessage connection for more information

  • Internationalization systems already provide messages like @@bidi_dir and @@ui_locale. Check the Predefined Messages link to see all the Predefined message names.

  • In the message.json file, each string available to the user has a name entry, a “message” entry, and an optional “description” entry. This name such as “extName” or “search_string” is the string ID, and “message” is the string value in the current locale. Description “has some explanatory information. Example:

    {
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}
Copy the code

    For more information, see Formats: Locale-Specific Messages.

Once you internationalize the extension, you can easily support other languages. 1. Copy message.json, translate the string, and save it in _locales. For example, to support Spanish, simply translate a message.json file and place it in _locales/es. The following figure shows the file hierarchy of the above extension with Support for Spanish.

Predefined messages

The internationalization system provides predefined messages to help you localize your extensions. These include @@uilocale(which you can use to detect the language of the current UI system), as well as messages preceded by @@bidi (used to detect text-oriented writing habits, like left-to-right writing in English), which have similar names, Examples include: Gadgets BIDI (bi-directional) API.

@@extension_ID message can be used in any extended CSS and JavaScript file, whether localized or not, but not in manifest.json files.

Note: Content Script CSS files cannot be used with predefined messages like @@extension_id. See Bug 39899 for more information.

The following table describes each predefined message.

The Message name describe
@@extension_id The ID of this extension; You can use this string inside the extension to construct urls to access certain resources. Extensions without localization can also use this message.

Note: you cannot use this in the manifest file message | | @ @ ui_locale | current language; You can use this string to construct locale-specific urls. | | @ @ bidi_dir | the text direction of the current locale, or “LTR” (representative from left to the language, such as English). Or RTL “(for languages from right to left, like Japanese). | | @ @ bidi_reversed_dir | the value of the @ @ bidi_dir invert. If @@bidi_dir is “LTR” then it is “RTL “, otherwise it is” LTR “. | | @ @ bidi_start_edge | if @ @ bidi_dir is “LTR”, it is the “left”, Otherwise it is “right”. | | @ @ bidi_end_edge | if @ @ bidi_dir is “LTR”, it is the “right”; , otherwise it is “left”. |

An example of constructing a URL with @@extension_id in a CSS file:

body { **background-image:url('chrome-extension://[email protected]@extension_id__/background.png'); * *}Copy the code

If the extension is abcdefghijklmnopqrstuvwxyzabcdef ID, then thick line part of the code above into:

background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');
Copy the code

An example of @@bidi_* messages in CSS files:

body { **direction: [email protected]@bidi_dir__; **} div#header {margin-bottom: 1.05em; overflow: hidden; Padding - bottom: 1.5 em. **[email protected]@bidi_start_edge__: 0; * * * * [email protected] @ bidi_end_edge__ : 1.5 em. ** position: relative; }Copy the code

Languages from left to right, such as English. The thick line becomes:

dir: ltr; padding-left: 0; Padding - right: 1.5 em.Copy the code

The language environment

The extension can use all of the languages supported by Google Chrome, plus several languages with several regional variations (e.g. En: en_GB for British English and en_US for American English).

Supported languages

Your extension can use any of the following languages:

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

How does the extension find strings

You do not have to define individual strings for each language. Internationalization-enabled extensions come with automatic search, and as long as these strings are identified in the message.json file in the default language, your extension will work regardless of the language. Here’s how the extension system searches for message.json:

  1. Search for messages files in the user’s preferred existing language. For example, if Google Chrome’s language is set to British English (en_GB), the system looks for _locales/en_GB/messages.json and stops the search if the file and its message exist.
  2. If the user’s preferred language code has an underlined locale identifier. Such as: en_US. The system will search for the en(without US) message file again. If the file and message exist, the system stops the search.
  3. Search messages files for the extension’s default language. Example: the default language is “ES”, then, search _locales/ES/messages. Json.

In the figure below, “Colores” message is supported in three languages and “extName” in two. American English users will always see the label “Colors”, British English users will see the label “Clours”, and they will see both the label “Hello World”. Since the default language is Spanish, non-English users will see the label “Colores” and the extension name “Hola Mundo “.

How to set the browser language

To test the translation, you may need to set the language of the browser. This section explains how to set languages on Windows,Mac OS X, and Linux.

Windows

You can change the language in location-Specific shortcuts or on the Google Chrome UI. Using shortcuts is faster and works in multiple languages simultaneously.

Use location-specific shortcuts

Create and use shortcuts to run language-specific Google Chrome:

  1. Copy a desktop shortcut for Google Chrome.

  2. Name a new shortcut with a language code, such as cn_chrome.lnk.

  3. Select the connection properties of the shortcut and add the –lang and –user-data-dir parameters. Such as:

    _path_to_chrome.exe_ --lang=_locale_ --user-data-dir=c:_locale_profile_dir_
Copy the code

  4. Double-click the new shortcut to run Chrome.

Example: Creating such a shortcut in Spanish:

_path_to_chrome.exe_ --lang=es --user-data-dir=c:chrome-profile-es
Copy the code

Example: You can create as many shortcuts as you want to make testing in multiple languages easy.

_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
Copy the code

Note: you don’t have to specify –user-data-dir, but as you can see, it’s easy to add this parameter. And specifying a user-data-dir directory for each language lets you run browsers in several languages at the same time. There is a downside, however, because the language data is not shared, so you need to install the extension multiple times (once for each language). If you don’t want to use this language, you don’t have to install it. See the Creating and Using Profiles connection for more information.

Use the UI

How to change the language using Google Chrome UI for Windows

  1. Set button (wrench icon) -> Options
  2. Select the current TAB
  3. Scroll to the end of the page
  4. Click “Change character and Language Settings”
  5. Select the language tag
  6. Use the drop-down list to set the Google Chrome language
  7. Restart the Chrome

Mac OS X

To change the language on a Mac, you need to use the system Preferences

  1. Select System Preferences from the Apple Menu
  2. In the Personal section, select International
  3. Choose your language and region
  4. Restart the chrome

Linux

To change the language on Linux, exit Google Chrome, set environment variables as follows, and restart:

LANGUAGE=es ./chrome
Copy the code

Some examples

You can easily find examples of internationalization in the examples/ API /i18n directory. A more complete example can be found in the Xamples/Extensions /news directory. Samples has additional code-level examples and help.

Example getMessage function

The following code shows how to get and display a localized string. Replace the two placeholders for message with “string1” and “string2”.

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}
Copy the code

How to supply and use a string.

_// 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."
    }
  }
}
Copy the code

Location-specific Messages Learn more about placeholders. See API Reference for more information about calling the function getMessage().

Example of the getAcceptLanguages function

The following example code shows how to take all available languages, concatenate them into strings with “, “and display them.

function getAcceptLanguages() { chrome.i18n.getAcceptLanguages(function(languageList) { var languages = languageList.join(","); document.getElementById("languageSpan").innerHTML = languages; })}Copy the code

See API Reference for more details on calling the function getAcceptLanguages().

Chrome. I18n

methods

getAcceptLanguages

chrome.i18n.getAcceptLanguages(functioncallback)

Make use of all available languages, a language spoken and browser, with Windows. The navigator. Language. Gets the language used by the browser

parameter

callback (function)

callback function

The callback argument should be a function like this:

function(array of string languages) {... };Copy the code

languages (array of string )

An array of languages accepted by the browser, similar to en-us,en, zh-cn

getMessage

string chrome.i18n.getMessage(string messageName, string or array of string substitutions)

Gets the string with the specified message. If message does not exist, this method returns an empty string. If the call format is wrong, such as messageName is not a string or Substitution is empty or greater than nine elements. This function returns “undefined”

parameter

messageName (string)

Message name, the name used in the messages.json file

substitutions (optionalstring or array of string)

If message requires this parameter, set the string from 1 to 9.

return

(string)

Message for the current language setting