skip to content

a.language

Description

Client side internationalization for AppStorm.JS. Using a.language you can define translate variable, and apply translate directly on client side.

The plugin also if fully compatible with a.state plugin allowing to auto-translate all html pages loaded.
Of course, the a.storage is also supported to keep translation language chosen by user between two application access.

You can found API here.


if storage plugin is activated, the system will automatically keep language chosen to reload language when user arrive next time.
if you want to deactivate auto-translate behavior, just don't set data-tr element tag.
if the HTML is not included into main page DOM, you must translate manually (see example 2).
before using this module, choose carefully the behavior (see below).


Setup

Javascript

To use this plugin, you must first setup language available, and set a default one:

// You can define what you want, just use the good one after!
a.language.setAllowed(["en", "fr", "jp"]);

// Setting the way a.language will translate HTML tag
a.language.setBehavior("erase");

// Setting the language
a.language.setCurrent("en");

The behavior allow to define how a.language will act when a data-tr is found, by default it's leave (or default/normal give same results). The normal behavior is to work around elements: if you got a data-tr on a p HTML tag, and that element include a tag, then the a.language will leave the a tag, and take care exclusively or direct text node. On erase mode, it will erase full content (including children), and replace by the translated content.
You can switch behavior at any time, we do recommend as much as you can to keep the default (leave) behavior, as it allow to make cascading data-tr (data-tr inside data-tr)…


If you don't use/setup “setCurrent”, the default language will be “en”.

If you don't use/setup “setAllowed”, the default array will be '[“en”, “fr”, “de”, “sp”]'.


Internationalization

Now you have to define translation for each language :

// Add language setup, and ask system to not auto-update
a.language.addTranslation("en", {
  "hello" : "hello world",
  "keyTranslate" : "some data"
}, false);
a.language.addTranslation("fr", {
  "hello" : "bonjour",
  "keyTranslate" : "quelques données"
}, false);

// We now have two key set: hello and keyTranslate for both French and English


HTML

To activate auto-translate system, you must define tag in HTML content :

  <a data-tr="keyTranslate"></a>
  <div>
    <a data-tr="hello"></a>
  </div>

The data-tr is the main translate tag. If the system does not find translate, it set the key as content (like <a data-tr=“hello”>hello</a>).

You can setup also variable in this system, with same syntax as Mustache.JS (see below).

From now you can dynamically use “setCurrent” to change language. Don't forget system automatically save language set by user, so you can also refresh your browser to see it in action.



Examples

From now we show up some of features not explain in this basic example :

Example 1: Using variables:

// Define variable, with same syntax as Mustache.JS
a.language.addTranslation("en", {
  "welcome" : "My name is {{name}}"
}, false);
a.language.addTranslation("fr", {
  "welcome" : "Mon nom est {{name}}"
}, false);

Usage:

  <a data-tr="welcome" data-tr-name="Richard"></a>

Using this system, you can include any parameter at any position.

Moreover, if a parameter does not exist (like we don't define data-tr-name) the system will drop name (including braces) to keep a nice presentation.


Example 2: Manual Translate:

// example 1: get translate (for current language set, with variable)
var tr = a.language.getSingleTranslation("welcome", {name : "Clement"});

// example 2: translate outside DOM html
var html = a.parser.xml.parse('<a data-tr="welcome" data-tr-name="roger"></a>');
// You don't need to retrieve data
a.language.translate(html);

// If you print HTML, it is already translated

As you see, you don't need to have HTML, or HTML inside DOM to use it, it's flexible…


Example 3: Force update:

The system should not need that (so you should not need that too), but if for any reason you must fully refresh html page, use translate:

// Full refresh page translation
a.language.translate();


Example 4: Setting global variable:

You can add global variable to language plugin, they will be override by local variable (if there is):

// Setting language (not refreshing page using "false")
a.language.setCurrent("en", false);

// Adding translation
a.language.addSingleTranslation("en", "welcome", "Welcome {{login}} to our new software", false);
a.language.addVariable("login", "global-login");

var withGlobal = a.language.getSingleTranslation("welcome");
alert(withGlobal);

var withLocal = a.language.getSingleTranslation("welcome", {login : "local-login"});
alert(withLocal);