v18n
v0.3.2
Published
Internationalization framework
Downloads
1
Maintainers
Readme
V18n
"Verkerhrsverbindungen"
Internationalization framework
The goal of v18n is to provide a simple API for localization based on and in line with the design principles of troop, sntls, and rubberband. In v18n, the central class is Translatable
, which, when serialized, resolves to a translation depending on the current locale settings. The library also introduces LocaleEnvironment
, a singleton that manages the current locale, as well as the LocaleBound
trait, which helps user-implemented classes to bind to locale changes.
Examples
JsFiddle: http://jsfiddle.net/danstocker/zwsutcL5/
For the examples below, we assume that the locale documents are properly initialized.
'locale/en-uk'.toDocument()
.setTranslations({
"You have {{appleCount}} {{appleForm}}.": "You have {{appleCount}} {{appleForm}}.",
"apple": ["apple", "apples"]
})
.setPluralFormula("nplurals=2; plural=(n != 1);");
'locale/de-de'.toDocument()
.setTranslations({
"You have {{appleCount}} {{appleForm}}.": "Sie haben {{appleCount}} {{appleForm}}.",
"apple": ["Apfel", "Äpfel"]
})
.setPluralFormula("nplurals=2; plural=(n != 1);");
In case we're loading these translations asynchronously, we might want to signal to the application that the locales are ready for use.
'en-uk'.toLocale().markAsReady();
'de-de'.toLocale().markAsReady();
Using Translatable
In order to tell v18n to translate a term, it has to be converted to a Translatable
. A Translatable
, when serialized by calling .toString()
on it, resolves to the specified term in the current language, provided that a match is found.
var apple = 'apple'.toTranslatable();
'en-uk'.toLocale().setAsCurrentLocale();
apple.toString() // 'apple'
'de-de'.toLocale().setAsCurrentLocale();
apple.toString() // 'Apfel'
Pluralization
Translatable
instances carry a multiplicity property, which they use in determining the correct plural form of the term.
var apple = 'apple'.toTranslatable()
.setMultiplicity(6);
'en-uk'.toLocale().setAsCurrentLocale();
apple.toString() // 'apples'
'de-de'.toLocale().setAsCurrentLocale();
apple.toString() // 'Äpfel'
Formatting
V18n uses the templating engine of rubberband, and thus allows expressions like the following.
var sentence = "You have {{appleCount}} {{appleForm}}.".toTranslatable().toLiveTemplate()
.addReplacements({
'{{appleCount}}': 6,
'{{appleForm}}': "apple".toTranslatable()
.setMultiplicity(6)
});
'en-uk'.toLocale().setAsCurrentLocale();
sentence.toString() // "You have 6 apples."
'de-de'.toLocale().setAsCurrentLocale();
sentence.toString() // "Sie haben 6 Äpfel."
Getting the current locale
The class LocaleEnvironment
manages the current localization state.
'de-de'.toLocale().setAsCurrentLocale();
v18n.LocaleEnvironment.create().getCurrentLocale().toString() // 'de-de'
Listening to locale changes
Components of the application might need to listen to locale changes. The event 'locale.ready.current' or v18n.LocaleEnvironment.EVENT_CURRENT_LOCALE_READY
signals that the current locale, already loaded and just changed, or previously set and just loaded, is ready for use.
v18n.LocaleEnvironment.create()
.subscribeTo(v18n.LocaleEnvironment.EVENT_CURRENT_LOCALE_READY, function () {
console.log("current locale is ready for use");
// updating widgets, etc.
});
Binding to locale changes
In order to bind instances of any class to locale changes,
- You'll need to apply (add & initialize) the
LocaleBound
trait to the class. - Elevate the handler method.
- Call
.bindToCurrentLocaleReady()
when the instance's life cycle begins. - Call
.unbindFromCurrentLocaleReady()
or.unbindAll()
when the instance's life cycle ends. - Implement the handler method.
For example,
var MyClass = troop.Base.extend()
.addTrait(v18n.LocaleBound)
.addMethods({
init: function () {
v18n.LocaleBound.init.call(this);
this.elevateMethod('onCurrentLocaleReady');
},
lifeCycleBegin: function () {
this.bindToCurrentLocaleReady(this.onCurrentLocaleReady);
},
lifeCycleEnd: function () {
this.unbindFromCurrentLocaleReady(this.onCurrentLocaleReady);
},
onCurrentLocaleReady: function () {
//... current locale is ready for use
}
});
This is a very common pattern for shoeshine widgets, which implement the callback methods afterAdd()
and afterRemove()
, corresponding to lifeCycleBegin()
and lifeCycleEnd()
in the example above.