Internationalization plugin for better-dom
The project aims to solve the internationalization problem on front-end side. The technique used behind the scenes I call “CSS-driven internationalization” and there is a deep article about it.
Features
- no JavaScript calls to switch to the current web page language
- change current language using the vanilla DOM
lang
attribute - support for HTML markup in localized string values
- ability to change language on a document subtree
NOTE: at present the project can't localize empty DOM elements (like <input>
, <select>
etc.) or attribute values.
Installing
Use bower to download this extension with all required dependencies.
$ bower install better-i18n-plugin
This will clone the latest version of the better-i18n-plugin into the bower_components
directory at the root of your project.
Then append the following scripts on your page:
Localization in browser
The plugin introduces 2 new static functions for the DOM
namespace: DOM.importStrings
and DOM.__
. The first one is used to populate DOM with new localizations for a particular language:
DOM;// you can populate many strings in one callDOM;
This storage is private therefore you can't access to it directly. Intstead you can use DOM.__
:
; // displays "Enter your name"// change current language...DOM; ; // displays "Введите ваше имя"
If you need to get a value for a particular language use toLocaleString
with an appropriate argument:
var entry = DOM; entry; // => "Enter your name"entry; // => "Введите ваше имя"
$Element
Usage with Let's say you need to localize a button to support multiple languages. In this case you can use $Element#l10n
:
button;
When you need to add a support for a new language import a localized version of the string. For example the string "Hello world"
can be translated for Russian we pages like below:
DOM;
Now for web pages where <html lang="ru">
the button displays "Привет мир"
instead of "Hello world"
.
String variables
Both DOM.__
and $Element#l10n
supports second optional argument:
DOM; // => "your Maksim"// arrays are supported tooDOM; // => "your Maksim" button; // displays "Hello Maksim"button; // displays "Hello Maksim"
Backend integration
Often you need to grab localized strings from backend. This is very easy to do using DOM.importStrings
. In the example below I'll use Handlebars as a templating language and i18n-node for I18N support.
Assume you've stored web page language in res.locals.locale
. Then you need to add another variable that stores all backend strings map passed into JSON.stringify
call:
// remember language of your web pagereslocalslocale = "ru";// generate string bundle for client sidereslocalsbundle = JSON;
After that just generate extra <script>
element that will populate all backend strings in browser:
... ... <!-- populate strings from backend -->
Now you can use DOM.__
with an appropriate key to get a backend string on client side.
Multilingual live extensions
In order to add support or use multiple languages of a live extension follow the convension below:
- All localizations are located inside if the
i18n
folder - File names have following format:
i18n\project.{lang}.js
- To use a particular language make sure you have an appropriate
lang
attribute on the<html>
element and the corresponsing file with localizations is included on your web page:
... ... <!-- required dependencies --> <!-- project files -->
Browser support
Desktop
- Chrome
- Safari 6.0+
- Firefox 16+
- Opera 12.10+
- Internet Explorer 8+ (see notes)
Mobile
- iOS Safari 6+
- Android 2.3+
- Chrome for Android