{"id":18045627,"url":"https://github.com/piroor/webextensions-lib-l10n","last_synced_at":"2025-04-10T01:33:13.784Z","repository":{"id":56017229,"uuid":"55592466","full_name":"piroor/webextensions-lib-l10n","owner":"piroor","description":"Provides ability to localize your HTML file with i18n messages.","archived":false,"fork":false,"pushed_at":"2024-11-12T09:08:28.000Z","size":16,"stargazers_count":10,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"trunk","last_synced_at":"2025-03-24T03:11:28.444Z","etag":null,"topics":["firefox-addon","webextensions"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piroor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-06T09:19:38.000Z","updated_at":"2024-11-12T09:08:32.000Z","dependencies_parsed_at":"2022-08-15T11:31:06.843Z","dependency_job_id":null,"html_url":"https://github.com/piroor/webextensions-lib-l10n","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piroor%2Fwebextensions-lib-l10n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piroor%2Fwebextensions-lib-l10n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piroor%2Fwebextensions-lib-l10n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piroor%2Fwebextensions-lib-l10n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piroor","download_url":"https://codeload.github.com/piroor/webextensions-lib-l10n/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248140579,"owners_count":21054310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firefox-addon","webextensions"],"created_at":"2024-10-30T18:13:48.303Z","updated_at":"2025-04-10T01:33:13.747Z","avatar_url":"https://github.com/piroor.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# webextensions-lib-l10n\n\nProvides ability to localize your HTML file with i18n messages.\n\n## Required permissions\n\nThis does not require any special permission.\n\n## Basic usage\n\nIn `manifest.json`, specify to load the file `l10n.js` for your HTML pages:\n\n```json\n{\n  \"default_locale\": \"en_US\",\n  \"options_ui\": {\n    \"page\": \"path/to/options.html\",\n    \"chrome_style\": true\n  }\n}\n```\n\n`options.html` is:\n\n```html\n\u003c!DOCTYPE html\u003e\n\n\u003cscript type=\"application/javascript\" src=\"./l10n.js\"\u003e\u003c/script\u003e\n\n\u003cp title=\"__MSG_config_enabled_tooltip__\"\u003e\n  \u003clabel\u003e\u003cinput type=\"checkbox\"\u003e\n         __MSG_config_enabled_label__\u003c/label\u003e\u003c/p\u003e\n\u003cp title=\"__MSG_config_advanced_tooltip__\"\u003e\n  \u003clabel\u003e\u003cinput type=\"checkbox\"\u003e\n         __MSG_config_advanced__\u003c/label\u003e\u003c/p\u003e\n\u003cp title=\"__MSG_config_attributes_tooltip__\"\u003e\n  \u003clabel\u003e__MSG_config_attributes_label_before__\n         \u003cinput type=\"text\"\u003e\n         __MSG_config_attributes_label_after__\u003c/label\u003e\u003c/p\u003e\n```\n\n`_locales/en_US/messages.json` is:\n\n~~~json\n{\n  \"config_enabled_label\":           { \"message\": \"Activate basic features\" },\n  \"config_enabled_tooltip\":         { \"message\": \"This is for general users.\" },\n  \"config_advanced_label\":          { \"message\": \"Activate advanced features\" },\n  \"config_advanced_tooltip\":        { \"message\": \"This is for power users.\" },\n  \"config_attributes_label_before\": { \"message\": \"List of attributes:\" },\n  \"config_attributes_label_after\":  { \"message\": \"\" }}\n  \"config_attributes_tooltip\":      { \"message\": \"You can specify mutlipe items delimited with \\\"|\\\".\" }\n}\n~~~\n\nThen, after the options page is loaded all texts in the document like `__MSG_*__` are filled with messages defined in locales.\n\n## Hide untranslated contents\n\nYou may see ugly untranslated messages in the contents until this library replaces `__MSG_*__` in the page.\nHere is an example to hide page contents until they are initialized:\n\n```css\n:root \u003e * {\n  transition: opacity 0.25s ease-out;\n}\n:root:not(.initialized) \u003e * {\n  opacity: 0;\n}\n```\n\nand:\n\n```javascript\nwindow.addEventListener('DOMContentLoaded', () =\u003e {\n  document.documentElement.classList.add('initialized');\n}, { once: true });\n```\n\n## Advanced usage\n\nThis 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.\n\n```javascript\nShortcutCustomizeUI.build().then(list =\u003e {\n  document.getElementById('shortcuts').appendChild(list);\n  l10n.updateDocument(); // resolve labels after initialized!\n});\n```\n\nDOM3 XPath doesn't find shadow nodes, so you need to call `updateSubtree()` for each shadow elements like:\n\n```javascript\nlt0n.updateSubtree(shadowRoot.querySelector('.root'));\n```\n\n## Important note for blank messages\n\nThis library keeps `__MSG_*__` texts as-is, if there is no effective message for the key.\nIf you want to define blank message intentionally for some reasons, please put `\\u200b` (`U+200B`, a zero width space) instead of blank string, like:\n\n```javascript\n{ \"before_link\": { \"message\": \"For more details, see \" } },\n{ \"link_text\":   { \"message\": \"the API document.\" } }\n{ \"after_link\":  { \"message\": \"\\u200b\" } }\n\n{ \"before_link\": { \"message\": \"\\u200b\" } },\n{ \"link_text\":   { \"message\": \"APIドキュメント\" } }\n{ \"after_link\":  { \"message\": \"に詳しい情報があります。\" } }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiroor%2Fwebextensions-lib-l10n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiroor%2Fwebextensions-lib-l10n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiroor%2Fwebextensions-lib-l10n/lists"}