webextensions-lib-l10n

Provides ability to localize your HTML file with i18n messages.

Required permissions

This does not require any special permission.

Basic usage

In manifest.json, specify to load the file l10n.js for your HTML pages:

{
  "default_locale": "en_US",
  "options_ui": {
    "page": "path/to/options.html",
    "chrome_style": true
  }
}

options.html is:

<!DOCTYPE html>

<script type="application/javascript" src="./l10n.js"></script>

<p title="__MSG_config_enabled_tooltip__">
  <label><input type="checkbox">
         __MSG_config_enabled_label__</label></p>
<p title="__MSG_config_advanced_tooltip__">
  <label><input type="checkbox">
         __MSG_config_advanced__</label></p>
<p title="__MSG_config_attributes_tooltip__">
  <label>__MSG_config_attributes_label_before__
         <input type="text">
         __MSG_config_attributes_label_after__</label></p>

_locales/en_US/messages.json is:

{
  "config_enabled_label":           { "message": "Activate basic features" },
  "config_enabled_tooltip":         { "message": "This is for general users." },
  "config_advanced_label":          { "message": "Activate advanced features" },
  "config_advanced_tooltip":        { "message": "This is for power users." },
  "config_attributes_label_before": { "message": "List of attributes:" },
  "config_attributes_label_after":  { "message": "" }}
  "config_attributes_tooltip":      { "message": "You can specify mutlipe items delimited with \"|\"." }
}

Then, after the options page is loaded all texts in the document like __MSG_*__ are filled with messages defined in locales.

Hide untranslated contents

You may see ugly untranslated messages in the contents until this library replaces __MSG_*__ in the page. Here is an example to hide page contents until they are initialized:

:root > * {
  transition: opacity 0.25s ease-out;
}
:root:not(.initialized) > * {
  opacity: 0;
}

and:

window.addEventListener('DOMContentLoaded', () => {
  document.documentElement.classList.add('initialized');
}, { once: true });

Advanced usage

This library has a method to resolve __MSG_*__ text labels in the document at any time. For example, labels generated by webextensions-lib-shortcut-customize-ui are appear in a form like this. In such case, you just need to execute l10n.updateDocument(); after those labels are embedded to the document.

ShortcutCustomizeUI.build().then(list => {
  document.getElementById('shortcuts').appendChild(list);
  l10n.updateDocument(); // resolve labels after initialized!
});

DOM3 XPath doesn't find shadow nodes, so you need to call updateSubtree() for each shadow elements like:

lt0n.updateSubtree(shadowRoot.querySelector('.root'));

Important note for blank messages

This library keeps __MSG_*__ texts as-is, if there is no effective message for the key. If you want to define blank message intentionally for some reasons, please put \u200b (U+200B, a zero width space) instead of blank string, like:

{ "before_link": { "message": "For more details, see " } },
{ "link_text":   { "message": "the API document." } }
{ "after_link":  { "message": "\u200b" } }

{ "before_link": { "message": "\u200b" } },
{ "link_text":   { "message": "APIドキュメント" } }
{ "after_link":  { "message": "に詳しい情報があります。" } }