:: libs :: 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://cdn.altersoftware.org/js-as-core/as-core.js" charset="UTF-8"></script>

before loading as-labels.js

Example of basic usage, loading from Altersoftware CDN:

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

In a easier way, using js-as-core tag modules attribute:

<script type="text/javascript" modules="labels" src="https://cdn.altersoftware.org/js-as-core/as-core.js" charset="UTF-8"></script>

Author and copyright

Developed and maintained by balestra

Licensed under Creative Commons Attribution 4.0 License for free personal/professional/commercial use, with attribution.

Downloads

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

js-as-core.tgz package.
js-as-labels.tgz package.

Configuration

Default language is en.
Page current language is detected automatically by <html> node tag, using lang or xml:lang attribute.
icons file icons.js is loaded by default.

Language detection sequence

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

The chain stops when a test matches:

The value of a cookie named forcelang
The lang attribute of <html> node
The xml:lang attribute of <html> node
The value of a cookie named language
The value of a cookie named lang
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:

AS.path.labels — String, the base path for labels.
AS.prop.defaultLang — String, the two-charactes language code for default
AS.labels.dontLoad — Regardless of content, prevent any label/icon files from loading
AS.labels.dontLoadAuto — Don’t load automatic label/icon files, they’ll be loaded with AS.labels.loadjs()
AS.labels.dontLoadIcons — Regardless of content, prevent icons files from loading
AS.labels.dontLabelize — Regardless of content, prevent HTML labels localization

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:

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".
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:

LabelName (string, mandatory) is the key defined in language files
options (object, optional, null or false to explicitly omit) is is a JavaScript object, key/values of string parameters
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:

All language and icons files must be UTF-8 encoded
All key/values defined in the default labgage file, if different, will be available
All key/values defined in the included file (e.g.: common-en.js) will be available
If a key/value couple is defined later a previous definition, it will override previous definition.

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:

language code (string, mandatory)
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.