https://github.com/t2ym/i18n-behavior
Instant and Modular I18n engine for lit-html and Polymer
https://github.com/t2ym/i18n-behavior
html-template i18n json lit-html polymer
Last synced: over 1 year ago
JSON representation
Instant and Modular I18n engine for lit-html and Polymer
- Host: GitHub
- URL: https://github.com/t2ym/i18n-behavior
- Owner: t2ym
- License: other
- Created: 2016-01-27T13:47:16.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-09-28T08:33:42.000Z (over 4 years ago)
- Last Synced: 2024-10-29T14:00:03.726Z (over 1 year ago)
- Topics: html-template, i18n, json, lit-html, polymer
- Language: JavaScript
- Homepage: https://github.com/t2ym/i18n-behavior#i18n-behavior
- Size: 14.5 MB
- Stars: 14
- Watchers: 4
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://travis-ci.org/t2ym/i18n-behavior)
[](https://coveralls.io/github/t2ym/i18n-behavior?branch=master)
[](https://www.npmjs.com/package/i18n-behavior)
[](https://www.webcomponents.org/element/t2ym/i18n-behavior)
# i18n-behavior
Instant and Modular I18N engine for [`lit-html`](https://lit-html.polymer-project.org/) and [Polymer](https://polymer-library.polymer-project.org/)
`html`\`\` tagged template literal API is provided by [`i18n-element`](https://github.com/t2ym/i18n-element)
## Compatible Versions
- Polymer library (`@polymer/polymer` NPM package) is configured as a **peer** dependency since 4.0.0
- Polymer elements using `I18nBehavior` must depend on `@polymer/polymer` NPM package themselves
| i18n-behavior | i18n-element | Polymer | lit-html |
|:---------------|:---------------|:--------|:---------|
| 5.x | 5.x | 3.x (optional) | 2.x |
| 4.x | 4.x | 3.x (optional) | 1.x |
| 3.x | 3.x | 3.x (mandatory) | 1.x |
| 2.x | 2.x | 1.x-2.x | - |
| 1.x | - | 1.x | - |
- [Changelog](https://github.com/t2ym/i18n-behavior/blob/master/CHANGELOG.md)
## Browser Compatibility
TODO: To be updated
| Browser | Chrome | Firefox | Edge 13+ | IE 11 | Safari 10+ | Chrome Android | Mobile Safari | Opera |
|:----------|:-------:|:--------:|:---------:|:------:|:---------:|:---------------:|:--------------:|:------:|
| Supported | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
- Polyfilled by `@webcomponents/webcomponentsjs/webcomponents-{bundle|loader}.js`
## Conceptual Workflow
- `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
## Install
```sh
npm install i18n-behavior
```
## Import for Polymer elements
```js
import { I18nBehavior } from 'i18n-behavior/i18n-behavior.js'
```
## Quick Tour
[I18N-ready `pwa-starter-kit`](https://github.com/t2ym/pwa-starter-kit)
```sh
npm install -g polymer-cli
git clone https://github.com/t2ym/pwa-starter-kit
cd pwa-starter-kit
npm ci
# Add Locales
gulp locales --targets="de es fr ja zh-Hans"
# I18N Process
gulp
# Translate XLIFF ./xliff/bundle.*.xlf
# Merge Translation
gulp
# Dev build on http://localhost:8080
polymer serve
# Static build
polymer build
# Static build on http://localhost:8080
cd build/{esm-unbundled|esm-bundled|es6-bundled|es5-bundled}
python -m SimpleHTTPServer -p 8080
```
## Usage in Polymer legacy syntax
- [API Docs](https://t2ym.github.io/i18n-behavior/)
- [Demo](https://t2ym.github.io/i18n-behavior/demo/preprocess/)
- ES6 class syntax support is provided by [`i18n-element`](https://github.com/t2ym/i18n-element)
### Run-time Automatic I18N
Apply `BehaviorsStore.I18nBehavior` or imported `I18nBehavior`
#### Source Code
```js
// Legacy Polymer syntax
Polymer({
importMeta: import.meta,
is: 'custom-element',
_template: html`
UI text label
`,
behaviors: [
I18nBehavior // Add this line for I18N
]
});
```
#### I18N-ready preprocessed DOM at element registration
Hard-coded UI text strings are automatically extracted and replaced with annotations bound to `text` object.
`lang` attribute specifies the current locale. By default, `` attribute is observed and
mirrored to those for I18N-ready element instances.
```html
...
{{text.label}}
...
```
If the containing element of the target text has `id` attribute, the string id is named with the `id` value.
If not, the string id is automatically generated. It is recommended to put meaningful `id` to each string
for robustness. When attaching `id` attribute is too much for the containing element, `text-id` attribute can be used instead.
```html
{{text.label}}
```
#### `text` dynamic property
`this.text` dynamic object property represents an object with UI text strings for the current locale.
```javascript
this.text = {
"label": "UI Text Label"
}
```
`this.text` dynamic object is SHARED among all the instances of the same custom element.
#### `model` dynamic property
`this.model` is deepcopied from `this.text.model` per instance to store I18N target attribute values.
UI text strings in I18N target attributes are automatically extracted and replaced with annotations
according to the shared repository (`i18n-attr-repo`) of I18N target attributes per elements
(like `placeholder` attribute of `input` element).
On `lang-updated` event, `this.text.model` is updated but `this.model` is NOT automatically updated
and needs explicit update like this.
```javascript
listeners: {
'lang-updated': '_langUpdated'
},
_langUpdated: function (event) {
if (Polymer.dom(event).rootTarget === this) {
this.model = deepcopy(this.text.model);
}
}
```
#### `` for manual text definitions
Optionally, any JSON data can be manually added to I18N target strings via `` element.
This option is effective for manual extraction of hard-coded UI text strings in JavaScript literals.
```html
...
[
"Responsive Web App boilerplate",
"Iron Elements and Paper Elements",
"End-to-end Build Tooling (including Vulcanize)",
"Unit testing with Web Component Tester",
"Routing with Page.js",
"Offline support with the Platinum Service Worker Elements"
]
{ "name": "Sam", "gender": "male" }
...
this.text.items[0] === 'Responsive Web App boilerplate'
this.text.sender.name === 'Sam'
...
```
#### Localized text strings fetched from JSON
While default text strings are extracted from the hard-coded strings in HTML template,
localized text strings are asynchronously fetched from JSON files under `locales` directory at the server.
```
/bundle.json
/locales/bundle.ja.json
/bundle.fr.json
/bundle.zh-Hans.json
/elements/my-list/my-list.json
/locales/my-list.ja.json
/my-list.zh-Hans.json
/google-chart-demo/google-chart-demo.json
/locales/google-chart-demo.ja.json
/google-chart-demo.fr.json
```
### Build-time Automatic I18N
[`gulp-i18n-preprocess`](https://github.com/t2ym/gulp-i18n-preprocess) filter performs build-time automatic I18N and embeds UI texts as JSON.
I18N-ready Source Code preprocessed by [`gulp-i18n-preprocess`](https://github.com/t2ym/gulp-i18n-preprocess):
```html
{{text.label}}
{
"label": "UI Text Label"
}
```
Default text values are immediately extracted from the embedded JSON
without overheads of run-time traversal into the whole template.
## License
[BSD-2-Clause](https://github.com/t2ym/i18n-behavior/blob/master/LICENSE.md)