L20n JavaScript API
var ctx = L20n.getContext();
ctx.linkResource('./locales/strings.l20n');
ctx.requestLocales();
When you freeze the context by calling requestLocales
, the resource files will be retrieved, parsed and compiled. You can listen to the ready
event (emitted by the Context
instance when all the resources have been compiled) and use ctx.getSync
and ctx.getEntitySync
to get translations synchronously.
Alternatively, you can register callbacks to execute when the context is ready (or when globals change and translations need to be updated) with ctx.localize
.
ctx.localize(['hello', 'new'], function(l10n) {
var node = document.querySelector('[data-l10n-id=hello]');
node.textContent = l10n.entities.hello.value;
node.classList.remove('hidden');
});
ctx.registerLocales(defaultLocale: String?, availableLocales: Array<String>?)
Register the default locale of the Context
instance, as well as all other locales available to the Context
instance before the language negotiation. Locales are referenced by their BCP 47 language codes.
ctx.registerLocales('en-US', ['ar', 'es-AR', 'es-ES', 'en-US', 'fr', 'pl']);
defaultLocale
is the original language of the Context
instance and will be used as the last fallback locale if other locales are registered. If it is undefined, or if registerLocales
hasn't been called at all, the Context
instance will create a special locale called i-default
to be used as the default.
availableLocales
is an array of all locales available to the Context
instance. This array (with defaultLocale
appended to it if it is not already present) will be used to negotiate the fallback chain for the user.
ctx.registerLocaleNegotiator(negotiator: Function)
Register a function which will be used to negotiate the locales supported by the Context
instance. If you don't call this function, L20n will use the built-in Intl.prioritizeLocales
negotiator.
ctx.registerLocaleNegotiator(function(available, requested, defLocale) { return Intl.prioritizeLocales(available, requested, defLocale); });
negotiator
is a function which takes the following arguments:
available
- all locales available to theContext
instance,requested
- locales preferred by the user,defLocale
- the default locale to be used as the ultimate fallback,callback
- the function to call when the negotiation completes (useful for asynchronous negotiators).
It must return an array which is the final fallback chain of locales, or if the negotiation is asynchronous, it must return a falsy value and call the callback
argument upon completion.
ctx.registerLocaleNegotiator(function(available, requested, defLocale, callback) { YourApp.getAllAvailableLanguages(function(allAvailable) { var fallbackChain = YourApp.intersect(allAvailable, requested); cb(fallbackChain); }); });
ctx.requestLocales(...requestedLocales: String?)
Specify the user's preferred locales for the Context
instance to negotiate against and freeze the Context
instance.
When a Context
instance is frozen, no more resources can be added or linked.
All IO related to fetching the resource files takes place when a Context
instance freezes. When all resources have been fetched, parsed and compiled, the Context
instance will emit a ready
event.
The final list of locales supported by the Context
instance will be negotiated asynchronously by the negotiator
registered by registerLocaleNegotiator
.
ctx.requestLocales('pl');
ctx.requestLocales('fr-CA', 'fr');
If requestedLocales
argument list is empty or undefined, the default locale from registerLocales
will be used.
ctx.requestLocales('pl');
If registerLocales
hasn't been called, the special i-default
locale is used, which means that the following minimal code is valid and will result in a fully operational Context
instance.
var ctx = L20n.getContext();
ctx.addResource('<hello "Hello, world!">');
ctx.requestLocales();
requestLocales
can be called multiple times after the Context
instance emitted the ready
event, in order to change the current language fallback chain, for instance if requested by the user.
ctx.supportedLocales
A read-only property which holds the current fallback chain of locales which was negotiated between all the available locales, the default locale and the user's preferred locales.
ctx.registerLocales('en-US', ['en-US', 'fr', 'pl']);
ctx.requestLocales('fr-CA', 'fr');
ctx.ready(function() {
// ctx.supportedLocales == ['fr'];
});
ctx.addResource(text: String)
Add a string as the content of a resource to the Context instance. The resource is added to all registered locales.
ctx.addResource('<hello "Hello, world!">');
ctx.linkResource(uri: String)
Add a resource identified by a URL to the Context instance. The resource is added to all registered locales.
ctx.linkResource('../locale/strings.l20n');
ctx.linkResource(template: Function)
Add a resource identified by a URL to the Context instance. The URL is constructed dynamically when you call requestLocales
. The function passed to linkResource
(called a template function) takes one argument which is the code of the current locale, which needs to be first registered with registerLocales
.
ctx.linkResource(function(locale) {
return '../locales/' + locale + '/strings.l20n';
});
The resource is added to all registered locales. If there are no registered locales (see registerLocales
), the default i-default
locale is used. In this case, addResource(String)
and linkResource(String)
might be better suited for adding resources.
ctx.addEventListener(event: String, callback: Function)
Register an event handler on the Context instance.
Currently available event types:
-
ready
- fired when all resources are available and theContext
instance is ready to be used. This event is also fired after each change to locale order (retranslation). -
error
- fired when an error occurs which prevents theContext
instance from working correctly or when the existing translations are buggy. The error object is passed as the first argument tocallback
. These errors include:-
Context.RuntimeError
, when an entity is missing or broken in all supported locales; in this case, L20n will show the the best available fallback of the requested entity in the UI: the source string as found in the resource, or the identifier. -
Context.TranslationError
, when the translation is present but broken in one of supported locales; theContext
instance will try to retrieve a fallback translation from the next locale in the fallback chain, -
Parser.Error
, when L20n is unable to parse the syntax of a resource; this might result in entities being broken which in turn can lead to above error being emitted.
-
-
warning
- fired when a less serious error occurs from which theContext
instance can recover gracefully and try to fetch a translations from a fallback locale. The error object is passed as the first argument tocallback
and can be one of the following:-
Context.Error
, when there are problems with setting up resources (e.g. a 404 error when fetching a resource file, or recursiveimport
statements in resource files), -
Context.TranslationError
, when there is a missing translation in one of supported locales; theContext
instance will try to retrieve a fallback translation from the next locale in the fallback chain, -
Compiler.Error
, when L20n is unable to evaluate an entity to a string; there are two types of errors in this category:Compiler.ValueError
, when L20n can still try to use the literal source string of the entity as fallback, andCompiler.IndexError
otherwise.
-
ctx.removeEventListener(event: String, callback: Function)
Remove an event listener previously registered with addEventListener
.
ctx.updateData(ctxdata: Object)
Update the context data which will be available to all entities in the context.
The ctxdata
is an object which extends the context data per key and per level of hierarchy. In other words, the following two calls:
ctx.updateData({ user: { name: "Bob" } });
ctx.updateData({ user: { gender: "masculine" } });
will make the internally-stored context data look like this:
{
"user" : {
"name": "Bob",
"gender": "masculine"
}
}
ctx.getSync(id: String, ctxdata: Object?)
Retrieve a string value of an entity called id
.
If passed, ctxdata
is a simple hash object with a list of variables that extend the context data available for the evaluation of this entity.
Returns a string.
ctx.getEntitySync(id: String, ctxdata: Object?)
Retrieve an object with data evaluated from an entity called id
.
If passed, ctxdata
is a simple hash object with a list of variables that extend the context data available for the evaluation of this entity.
Returns an object with the following properties:
value
: the string value of the entity,attributes
: an object of evaluated attributes of the entity,globals
: a list of global variables used while evaluating the entity,locale
: locale code of the language the entity is in; it can be different than the first locale in the current fallback chain if the entity couldn't be evaluated and a fallback translation had to be used.
ctx.localize(ids: Array<String>, callback: Function)
Registers a callback which fires when all entities listed in ids
have been retrieved.
ctx.localize(['hello', 'about'], function(l10n) {
var node = document.querySelector('[data-l10n-id=hello]');
node.textContent = l10n.entities.hello.value;
node.classList.remove('hidden');
});
The callback becomes bound to the entities on the ids
list. It will be called when the entities become available (asynchronously) or whenever the translation of any of the entities changes.
localize
should be the preferred way of localizing the UI.
The callback function is passed an l10n
object with the following properties:
entities
: an object whose keys are the identifiers and value are the entity objects as returned bygetEntitySync
,reason
: an object with the reason whycallback
was invoked.
The reason
object can be:
{ locales: Array<String> }
ifcallback
was invoked because of a change of the current locale (seerequestLocales
),{ global: String }
ifcallback
was invoked because the value of one of the globals used in the translation ofids
has changed.
ctx.ready(callback: Function)
Fires the function passed as argument as soon as the context is available.
If the context is available when the function is called, it fires the callback instantly. Otherwise it sets the event listener and fire as soon as the context is ready.
After that, each time locale list is modified (retranslation case) the callback will be executed.