https://github.com/piroor/webextensions-lib-l10n
Provides ability to localize your HTML file with i18n messages.
https://github.com/piroor/webextensions-lib-l10n
firefox-addon webextensions
Last synced: about 1 year ago
JSON representation
Provides ability to localize your HTML file with i18n messages.
- Host: GitHub
- URL: https://github.com/piroor/webextensions-lib-l10n
- Owner: piroor
- License: mit
- Created: 2016-04-06T09:19:38.000Z (about 10 years ago)
- Default Branch: trunk
- Last Pushed: 2024-11-12T09:08:28.000Z (over 1 year ago)
- Last Synced: 2025-03-24T03:11:28.444Z (about 1 year ago)
- Topics: firefox-addon, webextensions
- Language: JavaScript
- Size: 15.6 KB
- Stars: 10
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```json
{
"default_locale": "en_US",
"options_ui": {
"page": "path/to/options.html",
"chrome_style": true
}
}
```
`options.html` is:
```html
__MSG_config_enabled_label__
__MSG_config_advanced__
__MSG_config_attributes_label_before__
__MSG_config_attributes_label_after__
```
`_locales/en_US/messages.json` is:
~~~json
{
"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:
```css
:root > * {
transition: opacity 0.25s ease-out;
}
:root:not(.initialized) > * {
opacity: 0;
}
```
and:
```javascript
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](https://github.com/piroor/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.
```javascript
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:
```javascript
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:
```javascript
{ "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": "に詳しい情報があります。" } }
```