WCI18n is a lightweight i18n solution for web components, in API it is quite similar to Polymer.AppLocalizeBehavior but it is approaching the problem from a different angle.
WCI18n assumes native support for the following two APIs:
Promisefetch
If you don't have access to these two APIs in your target browser you will need to load them. Some quality polyfills can be found below:
There are a couple of distinct design differences between WCI18n and Polymer.AppLocalizeBehavior
Specifically:
- There is only 1 language allowed across the entire application
- Each registered custom element defines (and fetches) its own locales, there is no support for a single locale file
- Each component will fetch only the locales it needs for the current language (meaning that for production, inlining a formatted locale object is advisable)
WCI18n is included and used in your component as follows:
<dom-module id='custom-el'>
<template>
<!-- Use the provided `i18n` function -->
<p>[[i18n('key')]]</p>
</template>
<script>
class CustomEl extends Polymer.mixinBehaviors([WCI18n()], Polymer.Element) {
static get is() {
return 'custom-el';
}
/* ... */
}
customElements.define(CustomEl.is, CustomEl);
</script>
</dom-module><dom-module id='custom-el'>
<template>
<!-- Use the provided `i18n` function -->
<p>i18n('key')</p>
</template>
<script>
Polymer({
is: 'custom-el',
behaviors: [
WCI18n() // <-- Include the behavior
]
});
</script>
</dom-module>You can inject a translation object by passing a formatted locales object to the WCI18n function.
Formatted Object
{
"en": {
"key": "value"
},
"fr": {
"key": "valeur"
}
}
Example Injection
<dom-module id='custom-el'>
<template>
<!-- Use the provided `i18n` function -->
<p>i18n('key')</p>
</template>
<script>
Polymer({
is: 'custom-el',
behaviors: [
WCI18n({ en: { key: "value"}, fr: { key: "valeur" }}) // <-- Injected translations
]
});
</script>
</dom-module>Currently this component does not use the native Intl object and the IntlMessageFormat standards for legacy browser support. However
basic string interpolation is supported via 2 means:
key->valsequential string params- String format object
For example, if you take the following format string:
I love to take my {noun} to the {place}
You could do interpolation either of the following ways:
i18n('key', 'noun', 'cat', 'place', 'groomer');
i18n('key', { "noun": "cat", "place": "groomer" })
Both will create the following string:
I love to take my cat to the groomer
In addition to the typical component setup wc-i18n provides some addition functions that you can use to configure the language of your application
By pre-defining the window.WCI18n object you can create a new default language for your application.
This can be an easy way to set consistent global languages across multiple pages
Example:
<!DOCTYPE html>
<html>
<head>
<title>Define WCI18n</title>
<script>
// By predefining this object the language
// will default to 'ko' not 'en'
window.WCI18n = { language: 'ko' };
</script>
<!-- Web Components -->
<link rel='import' href="my/component/bundle.html">
</head>
<body>
...
</body>
</html>The WCI18n object now also exposes a setLanguage function that can be called to set the language to a given locale.
Example:
window.WCI18n.setLanguage('ko'); //- Sets language to 'ko'-
(Once) Install/Update the Polymer CLI:
npm i -g polymer-cli -
Run
bower ito load all of the dependencies. -
Run
polymer analyze > analysis.jsonto set up docs page. -
Run
polymer serve -oto run and view docs page including demo.
Please feel free to leave a github issue if there is a bug or feedback on how to improve this solution