{"id":17965366,"url":"https://github.com/t2ym/i18n-behavior","last_synced_at":"2025-03-25T07:31:04.096Z","repository":{"id":57270332,"uuid":"50510292","full_name":"t2ym/i18n-behavior","owner":"t2ym","description":"Instant and Modular I18n engine for lit-html and Polymer","archived":false,"fork":false,"pushed_at":"2021-09-28T08:33:42.000Z","size":15171,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-29T14:00:03.726Z","etag":null,"topics":["html-template","i18n","json","lit-html","polymer"],"latest_commit_sha":null,"homepage":"https://github.com/t2ym/i18n-behavior#i18n-behavior","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t2ym.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-27T13:47:16.000Z","updated_at":"2021-09-28T08:33:47.000Z","dependencies_parsed_at":"2022-08-31T04:22:48.829Z","dependency_job_id":null,"html_url":"https://github.com/t2ym/i18n-behavior","commit_stats":null,"previous_names":[],"tags_count":134,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t2ym%2Fi18n-behavior","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t2ym%2Fi18n-behavior/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t2ym%2Fi18n-behavior/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t2ym%2Fi18n-behavior/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t2ym","download_url":"https://codeload.github.com/t2ym/i18n-behavior/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245418249,"owners_count":20612093,"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":["html-template","i18n","json","lit-html","polymer"],"created_at":"2024-10-29T12:42:02.308Z","updated_at":"2025-03-25T07:31:03.035Z","avatar_url":"https://github.com/t2ym.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/t2ym/i18n-behavior.svg?branch=master)](https://travis-ci.org/t2ym/i18n-behavior)\n[![Coverage Status](https://coveralls.io/repos/github/t2ym/i18n-behavior/badge.svg?branch=master)](https://coveralls.io/github/t2ym/i18n-behavior?branch=master)\n[![npm](https://img.shields.io/npm/v/i18n-behavior.svg)](https://www.npmjs.com/package/i18n-behavior)\n[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/t2ym/i18n-behavior)\n\n# i18n-behavior\n\nInstant and Modular I18N engine for [`lit-html`](https://lit-html.polymer-project.org/) and [Polymer](https://polymer-library.polymer-project.org/)\n\n`html`\\`\\` tagged template literal API is provided by [`i18n-element`](https://github.com/t2ym/i18n-element)\n\n## Compatible Versions\n\n- Polymer library (`@polymer/polymer` NPM package) is configured as a **peer** dependency since 4.0.0\n- Polymer elements using `I18nBehavior` must depend on `@polymer/polymer` NPM package themselves\n\n| i18n-behavior  | i18n-element   | Polymer | lit-html |\n|:---------------|:---------------|:--------|:---------|\n| 5.x            | 5.x            | 3.x (optional) | 2.x      |\n| 4.x            | 4.x            | 3.x (optional) | 1.x      |\n| 3.x            | 3.x            | 3.x (mandatory) | 1.x      |\n| 2.x            | 2.x            | 1.x-2.x | -        |\n| 1.x            | -              | 1.x     | -        |\n\n- [Changelog](https://github.com/t2ym/i18n-behavior/blob/master/CHANGELOG.md)\n\n## Browser Compatibility\n\nTODO: To be updated\n\n| Browser   | Chrome  | Firefox  | Edge 13+  | IE 11  | Safari 10+ | Chrome Android  | Mobile Safari  | Opera  |\n|:----------|:-------:|:--------:|:---------:|:------:|:---------:|:---------------:|:--------------:|:------:|\n| Supported | ✔       | ✔        | ✔         | ✔      | ✔         | ✔               | ✔              | ✔      |\n\n- Polyfilled by `@webcomponents/webcomponentsjs/webcomponents-{bundle|loader}.js`\n\n## Conceptual Workflow\n\n- `demo/gulpfile.js` provides support for extracting UI strings from `html` tagged template literals in JavaScript sources as well as Polymer HTML templates in HTML Imports\n\n\u003cimg src=\"https://raw.githubusercontent.com/wiki/t2ym/i18n-behavior/PolymerI18nFlow.gif\" width=\"768px\"\u003e\n\n## Install\n\n```sh\n    npm install i18n-behavior\n```\n\n## Import for Polymer elements\n\n```js\n    import { I18nBehavior } from 'i18n-behavior/i18n-behavior.js'\n```\n\n## Quick Tour\n\n[I18N-ready `pwa-starter-kit`](https://github.com/t2ym/pwa-starter-kit)\n\n```sh\n    npm install -g polymer-cli\n    git clone https://github.com/t2ym/pwa-starter-kit\n    cd pwa-starter-kit\n    npm ci\n    # Add Locales\n    gulp locales --targets=\"de es fr ja zh-Hans\"\n    # I18N Process\n    gulp\n    # Translate XLIFF ./xliff/bundle.*.xlf\n    # Merge Translation\n    gulp\n    # Dev build on http://localhost:8080\n    polymer serve\n    # Static build\n    polymer build\n    # Static build on http://localhost:8080\n    cd build/{esm-unbundled|esm-bundled|es6-bundled|es5-bundled}\n    python -m SimpleHTTPServer -p 8080\n```\n\n## Usage in Polymer legacy syntax\n\n- [API Docs](https://t2ym.github.io/i18n-behavior/)\n- [Demo](https://t2ym.github.io/i18n-behavior/demo/preprocess/)\n- ES6 class syntax support is provided by [`i18n-element`](https://github.com/t2ym/i18n-element)\n\n### Run-time Automatic I18N\n\nApply `BehaviorsStore.I18nBehavior` or imported `I18nBehavior`\n\n#### Source Code\n\n```js\n    // Legacy Polymer syntax\n    Polymer({\n      importMeta: import.meta,\n      is: 'custom-element',\n      _template: html`\n        \u003cspan id=\"label\"\u003eUI text label\u003c/span\u003e \u003c!-- no need to touch UI text strings --\u003e\n      `,\n      behaviors: [\n        I18nBehavior // Add this line for I18N\n      ]\n    });\n```\n\n#### I18N-ready preprocessed DOM at element registration\n\nHard-coded UI text strings are automatically extracted and replaced with annotations bound to `text` object.\n\n`lang` attribute specifies the current locale. By default, `\u003chtml lang\u003e` attribute is observed and\nmirrored to those for I18N-ready element instances.\n\n```html\n    \u003chtml lang=\"en\"\u003e\u003c!-- html lang attribute is observed and mirrored --\u003e\n      ...\n      \u003ccustom-element lang=\"en\"\u003e\n        \u003cspan id=\"label\"\u003e{{text.label}}\u003c/span\u003e\u003c!-- UI texts are bound to text object --\u003e\n      \u003c/custom-element\u003e\n      ...\n    \u003c/html\u003e\n```\n\nIf the containing element of the target text has `id` attribute, the string id is named with the `id` value.\nIf not, the string id is automatically generated. It is recommended to put meaningful `id` to each string \nfor robustness. When attaching `id` attribute is too much for the containing element, `text-id` attribute can be used instead.\n\n```html\n    \u003cspan text-id=\"label\"\u003e{{text.label}}\u003c/span\u003e\n```\n\n#### `text` dynamic property\n\n`this.text` dynamic object property represents an object with UI text strings for the current locale.\n\n```javascript\n    this.text = {\n      \"label\": \"UI Text Label\"\n    }\n```\n\n`this.text` dynamic object is SHARED among all the instances of the same custom element.\n\n#### `model` dynamic property\n\n`this.model` is deepcopied from `this.text.model` per instance to store I18N target attribute values.\nUI text strings in I18N target attributes are automatically extracted and replaced with annotations\naccording to the shared repository (`i18n-attr-repo`) of I18N target attributes per elements \n(like `placeholder` attribute of `input` element).\n\nOn `lang-updated` event, `this.text.model` is updated but `this.model` is NOT automatically updated\nand needs explicit update like this.\n\n```javascript\n    listeners: {\n      'lang-updated': '_langUpdated'\n    },\n\n    _langUpdated: function (event) {\n      if (Polymer.dom(event).rootTarget === this) {\n        this.model = deepcopy(this.text.model);\n      }\n    }\n```\n\n#### `\u003cjson-data\u003e` for manual text definitions\n\nOptionally, any JSON data can be manually added to I18N target strings via `\u003cjson-data\u003e` element.\nThis option is effective for manual extraction of hard-coded UI text strings in JavaScript literals.\n\n```html\n  \u003cdom-module id=\"my-element\"\u003e\n    \u003ctemplate\u003e\n      ... \u003c!-- ordinary template for rendering --\u003e\n      \u003ctemplate\u003e\u003c!-- containing template element to avoid rendering --\u003e\n        \u003cjson-data id=\"items\"\u003e[\n          \"Responsive Web App boilerplate\",\n          \"Iron Elements and Paper Elements\",\n          \"End-to-end Build Tooling (including Vulcanize)\",\n          \"Unit testing with Web Component Tester\",\n          \"Routing with Page.js\",\n          \"Offline support with the Platinum Service Worker Elements\"\n        ]\u003c/json-data\u003e\n        \u003cjson-data id=\"sender\"\u003e{ \"name\": \"Sam\", \"gender\": \"male\" }\u003c/json-data\u003e\n      \u003c/template\u003e\n    \u003c/template\u003e\n    \u003cscript\u003e\n    ...\n    this.text.items[0] === 'Responsive Web App boilerplate'\n    this.text.sender.name === 'Sam'\n    ...\n    \u003c/script\u003e\n  \u003c/dom-module\u003e\n```\n\n#### Localized text strings fetched from JSON\n\nWhile default text strings are extracted from the hard-coded strings in HTML template,\nlocalized text strings are asynchronously fetched from JSON files under `locales` directory at the server.\n\n```\n    /bundle.json\n    /locales/bundle.ja.json\n            /bundle.fr.json\n            /bundle.zh-Hans.json\n    \n    /elements/my-list/my-list.json\n                     /locales/my-list.ja.json\n                             /my-list.zh-Hans.json\n    \n             /google-chart-demo/google-chart-demo.json\n                               /locales/google-chart-demo.ja.json\n                                       /google-chart-demo.fr.json\n```\n\n### Build-time Automatic I18N\n\n[`gulp-i18n-preprocess`](https://github.com/t2ym/gulp-i18n-preprocess) filter performs build-time automatic I18N and embeds UI texts as JSON.\n\nI18N-ready Source Code preprocessed by [`gulp-i18n-preprocess`](https://github.com/t2ym/gulp-i18n-preprocess):\n\n```html\n    \u003cdom-module id=\"custom-element\"\u003e\n      \u003ctemplate localizable-text=\"embedded\"\u003e\n        \u003cspan id=\"label\"\u003e{{text.label}}\u003c/span\u003e\n        \u003ctemplate id=\"localizable-text\"\u003e\n          \u003cjson-data\u003e{\n            \"label\": \"UI Text Label\"\n          }\u003c/json-data\u003e\n        \u003c/template\u003e\n      \u003c/template\u003e\n    \u003c/dom-module\u003e\n```\n\nDefault text values are immediately extracted from the embedded JSON \nwithout overheads of run-time traversal into the whole template.\n\n## License\n\n[BSD-2-Clause](https://github.com/t2ym/i18n-behavior/blob/master/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft2ym%2Fi18n-behavior","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft2ym%2Fi18n-behavior","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft2ym%2Fi18n-behavior/lists"}