i18n-element

I18N Base Element for Polymer 2.x


Keywords
polymer, polymer2, web-component, web-components, i18n, internationalization, l10n, localization, format, ES6, ES2015, html-template, lit-html
License
BSD-2-Clause
Install
bower install i18n-element

Documentation

Build Status Coverage Status npm Published on webcomponents.org

i18n-element

I18N Base Element for Lit and Polymer with i18n-behavior as I18N engine

  • i18n-element inserts I18N layer into UI definitions in HTML templates transparently
  • i18n-element comes with the full-featured automation tools

Extendable and composable HTML template literals based on lit-html

import { html, i18n, bind } from 'i18n-element/i18n.js';

class MyI18nElement extends i18n(HTMLElement) {
  ... // a few boilerplate mandatory methods are omitted here
  render() {
    return html`${bind(this, 'my-i18n-element')}
      <span>localizable message with ${this.property}</span>`;
  }
  ...
}

class ExtendedElement extends MyI18nElement {
  render() {
    return html`${bind(this, 'extended-element')}
      <div>extended message with ${this.property}</div>
      ${super.render()}`;
  }
}

class CompositeElement extends i18n(HTMLElement) {
  render() {
    return html`${bind(this /* bound to 'composite-element' */)}
      <div>composite element with ${getMessage()}</div>
      <extended-element></extended-element>`;
  }
}

const binding = bind('get-message', import.meta); // bound to a pseudo-element name

const getMessage = () => html`${'get-message', binding}<span>get message</span>`;
  • Each HTML template literal is bound to its unique (pseudo-)element name
  • Fetch JSON for locale resources at locales/{element-name}.{locale}.json

Install

npm install i18n-element

Import

  • lit-html elements
import { html, i18n, bind } from 'i18n-element/i18n.js';
  • Polymer elements
import { Localizable } from 'i18n-element/i18n-element.js';

Quick Tour

I18N-ready pwa-starter-kit

    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 8080

Syntax

I18N for lit-html elements

import { html, i18n, bind } from 'i18n-element/i18n.js';

class AwesomeElement extends i18n(HTMLElement) {
  static get importMeta() { return import.meta; }
  constructor() {
    super();
    this.attachShadow({mode: 'open'});
    this.addEventListener('lang-updated', this._langUpdated.bind(this));
  }
  connectedCallback() { this.invalidate(); }
  _langUpdated(event) { this.invalidate(); }
  render() {
    return html`${bind(this, 'awesome-element')}
      <div>localizable message from ${this.is}</div>`;
  }
  invalidate() {
    render(this.render(), this.shadowRoot);
  }
}
customElements.define('awesome-element', AwesomeElement);
    # npm run demo === cd demo; gulp
    # Add locales
    npm run demo -- locales --targets="de es fr ja zh-Hans"
    # I18N process
    npm run demo

Localizable mixin for Polymer elements

Demo Source

import { LegacyElementMixin } from '@polymer/polymer/lib/legacy/legacy-element-mixin.js';
import { html } from '@polymer/polymer/lib/utils/html-tag.js';

import { Localizable } from 'i18n-element/i18n-element.js';

class LocalizableElement extends Localizable(LegacyElementMixin(HTMLElement)) {
  static get importMeta() { return import.meta; }
  static get template() {
    return html`<span id="label1">Localizable UI label 1</span>`;
  }
  static get is() { return 'localizable-element'; }
}
customElements.define(LocalizableElement.is, LocalizableElement);

Define = class Thin Definition Syntax

import 'i18n-element/define-element.js';

Define = class ThinElement extends Localizable(LegacyElementMixin(HTMLElement)) {
  static get importMeta() { return import.meta; }
  static get template() {
    return html`<span id="label1">Localizable UI label 1</span>`;
  }
  // static get is() can be omitted
}
// customElements.define() can be omitted

I18N-ready Bound Element i18n-dom-bind based on Polymer dom-bind

import 'i18n-element/i18n-dom-bind.js';
  • Based on Polymer dom-bind Element
  • i18n-dom-bind element must have id attribute

Demo Source

<i18n-dom-bind id="el5">
  <template>
    <span id="label1">Bound UI label 1</span>
  </template>
</i18n-dom-bind>

Tools

Full-featured automation tools are available

Module NPM version Description
gulp-i18n-preprocess npm Build-time I18N preprocessor
gulp-i18n-leverage npm L10N JSON updater
gulp-i18n-add-locales npm L10N JSON placeholder generator
xliff-conv npm XLIFF/JSON converter
live-localizer npm L10N widget with Firebase storage
i18n-element npm I18N base element class
i18n-behavior npm Run-time I18N handler
i18n-format npm I18N text formatter
i18n-number npm I18N number formatter

They are fully integrated in these samples:

Configurations in demo/gulpfile.js - npm run demo to trigger I18N automation

    const useI18nCoreJs = true; // true to use i18n-core.js for preprocessed scripts
    const useI18nFormatDataProperty = true; // true to proprocess to <i18n-format .data=${data}><json-data preprocessed>
    // Diretories are relative to the current directory
    var srcDir = 'clock'; // source files directory before preprocessing; should be changed to 'src' or whatever the target project is configured with
    var tmpDir = 'tmp'; // temporary directory for I18N preprocessing
    var destDir = 'preprocess'; // directory for preprocessed files
    const minifyHtmlTemplates = false; // true to minify HTML template literals (experimental)
    const htmlMinifierOptions = { // options for minification of HTML template literals
      // Same options as polymer build minify: true
      collapseWhitespace: true,
      removeComments: true,
    };
    const extractAnonymousTemplates = false; // true For Polymer 3.0 templates

Compatible Versions

i18n-element i18n-behavior 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 -
  • Polymer elements using i18n-element.js must depend on @polymer/polymer NPM package themselves

Browser Compatibility

  • TODO: To be updated
  • Polyfilled by @webcomponents/webcomponentsjs/webcomponents-{bundle|loader}.js
Browser Chrome Firefox Edge 13+ IE 11 Safari 10+ Chrome Android Mobile Safari Opera
Supported ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔

License

BSD-2-Clause