stonejs¶

This modules integrates the stonejs library to the ObsidianJS framework.

The purpose of stonejs is to provide internationalization to your Javascript application.

Using This Module¶

First add the module to your project:

npm install --save @obsidianjs/stonejs

Then use it in your application (in your main index.js):

const obsidian = require("@obsidianjs/obsidian");
const stonejs = require("@obsidianjs/stonejs");

const app = obsidian("my-application");
app.use(stonejs);
app.start();

Config¶

initialLang The initial langage of the application default to “C”

Stonejs API¶

Functions¶

stonejs.gettext(string, replacements={})¶

Translates the given string to the current language.

Arguments:	string (string) – The string to translate. replacements (Object) – an object containing replacements for the string (optional, see example below).
Return type:	string
Returns:	The translated string.

var text1 = stonejs.gettext("Hello World");
var text2 = stonejs.gettext("Hello {name}", {name: "John"});

Note

You may not use this function from this module. It is better to import direclty stonejs and using it this way:

const _ = require("stonejs").gettext

var text1 = _("Hello World");

stonejs.lazyGettext(string, replacements={})¶

Same as stonejs.gettext but returns a stonejs.LazyString() instead of a String.

Note

You may not use this function from this module. It is better to import direclty stonejs and using it this way:

const _ = require("stonejs").lazyGettext

var text1 = _("Hello World");

stonejs.addCatalogs(catalogs)¶

Adds one (or more if you merged multiple languages into one file) string catalog.

Arguments:	catalogs (Object) – An object containing translated strings (catalogs can be built using stronejs-tools).

stonejs.addCatalogs(catalogs);

stonejs.getLocale()¶

Returns the current locale (aka target language for the gettext and lazyGettext functions). The default locale is "C" (it means no translation: simply returns the string as it is in the source).

Return type:	string
Returns:	The current locale.

var locale = stonejs.getLocale();
// "c", "en", "fr", ...

stonejs.setLocale(locale)¶

Defines the current locale (aka the target language for the gettext and lazyGettext functions).

Note

You can use the stonejs.setBestMatchingLocale() function to set the best language for the user.

Arguments:	locale (string) – The locale code (e.g. `"en"`, `"fr"`, …)
Events:	`locale-changed`

stonejs.setLocale("fr");

stonejs.setBestMatchingLocale(locales)¶

Find and set the best language for the user (depending on available catalogs and given language list).

Arguments:	locales (string\|Array) – (optional) The locale(s) to choose from (e.g. `"fr"`, `["fr", "fr_FR", "en_US"]`).
Events:	`locale-changed`

stonejs.setBestMatchingLocale();  // Automaticaly set the best language (from informations given by the browser)
setBestMatchingLocale("fr");    // Finds the catalog that best match "fr" ("fr", "fr_FR", fr_*,...)
setBestMatchingLocale(["fr", "en_US", "en_UK"]);    // Finds the best available catalog from the given list

stonejs.findBestMatchingLocale(locales, catalogs)¶

Find and return the given locale that best matches the given catalogs.

Arguments:	locales (string\|Array) – The locale(s) to choose from (e.g. `"fr"`, `["fr", "fr_FR", "en_US"]`). catalogs (Array) – the list of available catalogs (e.g. `["fr_FR", "en"]`).

stonejs.findBestMatchingLocale(["fr"], ["pt_BR", "fr_CA", "fr_FR"]);  // -> "fr_FR"

stonejs.guessUserLanguage()¶

Tries to guess the user language (based on the browser’s preferred languages).

Return type:	string:
Returns:	The user’s language.

var locale = stonejs.guessUserLanguage();

stonejs.enableDomScan(enable)¶

Allows stonejs.js to scan all the DOM to find translatable strings (and to translate them).

Arguments:	enable (boolean) – Enable the scan of the DOM if true, disable it otherwise.

stonejs.enableDomScan(true);

Warning

This feature should probably not be used with ObsidianJS projects.

stonejs.updateDomTranslation()¶: Updates the DOM translation if DOM scan was enabled with stonejs.enableDomScan (re-scan and re-translate all strings).

Warning

This method should probably not be used with ObsidianJS projects.

The LazyString Class¶

class stonejs.LazyString(string)¶

stonejs.LazyString is an object returned by the stonejs.lazyGettext() function. It behaves like a standard String object (same API) but its value changes if you change the locale with stonejs.setLocale() function.

This is useful when you have to define translatable strings before the string catalog was loaded, or to automatically re-translate strings each time the locale is changed.

You can find an example of its use in the PhotonUI documentation:

http://wanadev.github.io/PhotonUI/doc/widgets/translation.html

Events¶

locale-changed¶

Triggered when the locale changes.

Callback:

function(newLocale)¶

Arguments:	newLocale (string) – The new locale

app.events.on("@stonejs.locale-changed", (newLocale) => {
    // ...
})