Awesome Open Source
Awesome Open Source

Build Status Coverage Status npm Published on


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 ${}</span>`;

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

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

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


npm install i18n-element


  • 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
    cd pwa-starter-kit
    npm ci
    # Add Locales
    gulp locales --targets="de es fr ja zh-Hans"
    # I18N Process
    # Translate XLIFF ./xliff/bundle.*.xlf
    # Merge Translation
    # 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


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() {
    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 ${}</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);

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">
    <span id="label1">Bound UI label 1</span>


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



Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Es6 (1,049,823
Html (237,920
I18n (4,820
Webcomponents (3,700
Polymer (3,242
Custom Elements (1,032
L10n (653
Html Template (642
Lit Element (214
Lit Html (185