Unlike other i18n/l10n libraries, html10n.js provides:
- declarative localization: elements with
l10n-*attributes are automatically translated when the document is loaded - named variables instead of printf-like
%stokens - a simple and full-featured pluralization system
Thanks to @fabi1cazenave for his original work on webL10n on which this project is based. Instead of featuring some *.ini/*.properties/*.lol format, this project expects translations to be provided in JSON for easier handling in JavaScript and better client-side performance.
Here’s a quick way to get a multilingual HTML page:
<html>
<head>
<script type="text/javascript" src="l10n.js"></script>
<link rel="localizations" href="i18n.json" type="application/l10n+json"/>
</head>
<body>
<button data-l10n-id="test" title="click me!">This is a test</button>
</body>
</html>- l10n resource files are associated to the HTML document with a
<link>element - translatable elements carry a
data-l10n-idattribute and optionally adata-l10n-argsattribute containing the message arguments as JSON. - l10n resources are stored in a bullet-proof
*.jsonfile:
{
"en": {
"test": "This is a test",
"test.title": "click me!"
},
"fr": {
"test": "Ceci est un test",
"test.title": "cliquez-moi!"
}
}html10n.js exposes a rather simple API, all contained in the html10n object.
localizedevent: fired when the page has been translated;localizemethod: set the ISO-639-1 code of the current locale and start translating the document;getmethod: get a translated string.
html10n.bind("localized", function() {
console.log("Localized!");
});
html10n.localize('fr');var message = html10n.get('test');
alert(message);You will probably use the gettext-like alias:
alert(_('test'));To handle complex strings, the get() method can accept optional arguments:
alert(_('welcome', { user: "John" }));where welcome is defined like this:
{
"en": {
"welcome": "welcome, {{user}}!"
},
"fr": {
"welcome": "bienvenue, {{user}} !"
}
}You can specify a default value in JSON for any argument in the HTML document with the data-l10n-args attribute. In the last example, that would be:
<p data-l10n-id="welcome" data-l10n-args='{ "user": "your awesomeness" }'>Welcome!</p>If you don’t want to have all your locales in a single file, simply use an include rule in your locale files to include another language:
{ "en": {
// ...
},
"fr": "/locales/fr.json",
"nl": "/locales/nl.json"
}The following string might be gramatically incorrect when n equals zero or one:
"unread": "You have {{n}} unread messages"
This can be solved by using the pre-defined plural() macro:
{
"en": {
"unreadMessages": "You have {{n}} unread {[ plural(n) one: message, other: messages ]}"
}
}Here, plural() is a macro taking a selector param based on which it picks on of the provided options.
plural() chooses between zero | one | two | few | many | other, depending on the param (n) and the current language, as specified in the Unicode plural rules. If one of these indexes isn’t specified in your message, other will be used instead.
Macros are defined in html10n.macros as functions taking the following arguments: (key, param, opts), where
key(String) is the key of the current messageparam(mixed) is the value of the argument, passed as the macro parameteropts(Object) is a hash of options that may be used to produce the output (s.plural()macro above)
All macros should return a string that will replace the macro in the message.
By default, we currently assume that all strings are applied to the textContent DOM node property.
However, you can modify other properties of the appropriate DOM node by appending the property name like so:
welcome.innerHTML = welcome, <strong>{{user}}</strong>!Should work with Firefox, Chrome, Opera and Internet Explorer 6 to 10.
MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent