altersoftware.IT
altersoftware.IT
altersoftware.IT

jslibs/js-as-labels

AS.labels object, AS.label() and AS.icon() methods

Create multilanguage pages client-side, for both HTML and JavaScript.

Requires

Requires as-core.js (AS JavaScipt object), load:

<script type="text/javascript" src="https://altersoftware.it/products/jslibs/js-as-core/as-core.js" charset="UTF-8"></script>

before loading as-labels.js

Example of basic usage, loading from Altersoftware server:

<script type="text/javascript" src="https://altersoftware.it/products/jslibs/js-as-core/as-core.js" charset="UTF-8"></script>
<script type="text/javascript" src="https://altersoftware.it/products/jslibs/js-as-labels/as-labels.js" charset="UTF-8"></script>

Downloads

All downloads are refreshed daily from the latest stable branch of Altersoftware GIT repository.

Configuration

Language detection sequence

as-labels.js tries to detect actual language by performing several tests.

The chain stops when a test matches:

  1. The value of a cookie named forcelang
  2. The lang attribute of <html> node
  3. The xml:lang attribute of <html> node
  4. The value of a cookie named language
  5. The value of a cookie named lang
  6. Default language

Configuration using <meta> tags

Use META tags to pass configuration to AS.labels, like in:

<meta name="AS.path.labels" content="/myapp/styles/locale/mypage-" />
<meta name="AS.labels.dontLoadIcons" content="true" />

This in the example is the base path for label files.
The language suffix is then added (e.g.: mypage-en.js).
Icons file will be searched in /myapp/styles/locale/icons.js.

Available META tags are:

Basic use in HTML

Even when both AS.labels.dontLoad and AS.labels.dontLabelize are in place, as-labels.js is still useful.

It parses body content for nodes with "lang" attribute, makes a list of available languages and compares it to the list of the preferred languages declared by bower’s user preferences.

By doing this as-labels.js determines the best language matching user preference, then hides all the DOM nodes with a different "lang" attribute.

Notes:

  1. To force another language in the browser and override both the browser and the document, it’s always possible to use a cookie named "forcelang".
  2. Actual show/hide of DOM nodes is performed by ´AS.labels.page()´ method.

Use in HTML

Use syntax: {{label:myLabelName}} or {{icon:UserIcon}}

Optionally you can user parameters: {{label:Greetings}{firstName:Bob}}

Labels are automatically converted at page load time.

Advanced use in HTML

In case you create/import further HTML with label tags, you can invoke AS.labels.labelizeAll() to trigger a conversion for new label tags.
In alternative you can limit conversion to a DOM node, e.g.: AS.labels.labelize(document.getElementById('newDiv'));

Hint: if you just created a DOM element, you may need to defer labels localization to a time when DOM is refreshed.

In this case you can use a setTimeout:

function addLocalixedText( userName ) {
    let mydiv = document.createElement("div");
    mydiv.innerHTML = '{{label:Greetings}{firstName:'+userName+'}}';
    document.getElementsByTagName('body')[0].appendChild( mydiv );
    // Now you could use: window.setTimeout(AS.labels.labelizeAll,10);
    // or, better:
    window.setTimeout(function(){ AS.labels.labelize(mydiv); },10);
}
/*
    Please note: the above example is mainly related
    to imported text snippets.
    From JavaScript you should rather use:
*/
function addLocalixedText( userName ) {
    let mydiv = document.createElement("div");
    mydiv.innerHTML = AS.label('Greetings',{firstName:userName});
    document.getElementsByTagName('body')[0].appendChild( mydiv );
}

Use in JavaScript

Use syntax: AS.label('myLabelName') or AS.icon('UserIcon')

Optionally you can user parameters: AS.label('Greetings',{firstName:'Bob'})

AS.label() method accepts up to 3 parameters:

  1. LabelName (string, mandatory) is the key defined in language files
  2. options (object, optional, null or false to explicitly omit) is is a JavaScript object, key/values of string parameters
  3. language (string, optional, defaults to current language) is the language of the label

AS.icon() doesn't accept parameters.
If you built your icons with parameters, you can use: AS.label('iconName',{key:'value'},'icons')

JavaScript language files

Your javascript language file will look like:

AS.labels.include('common-en');
AS.labels.load('en',[{
    // ....
    'GreetFormula' : 'Welcome',
    'Greetings' : "{{label:GreetFormula}}, dear {{firstName|Unknown}}",
    // ....
}]);

In case the parameter firstname isn’t passed, its default value will be Unknown.

Notes:

AS.labels.include()

Accepts one string parameter, the name (without the trailing “.js”) of the file to be loaded.

Path starts from current language file folder.

AS.labels.load()

Accepts two parameters:

  1. language code (string, mandatory)
  2. Mandatory, lists key/values as a JavaScript object as well as an array of JavaScript objects.

AS.labels.init( [lang] )

Force the re-initialization of as-labels.js, optionally passing a parameter for a specific language.

After re-initialization labels are checked again and AS.labels.page() is triggered.

AS.labels.page( [ShowAllflag] )

Automatically triggered by AS.labels.init().

Perform user browser language analysis, compares them to languages used in DOM nodes with lang attribute, determines best language option and show/hide DOM nodes with lang attribute accordingly.

Invoked with a true parameter shows all DOM nodes with a lang attribute.

icons

icons is simply another language, with the special language code “icons”.

icons.js is a langage list as above, like:

AS.labels.load('icons', {
    'calendar' : '<svg xmlns="http://www.w3.org/2000/svg" viewBox="2 2 28 28"><path … /></svg>',
    'user' : '👴',
});

The peculiarity of icons file (language) is that it’s shared across all different languages.

You can use it for graphic elements, as well as for shared labels amiong all languages.