Standalone API

Accessing locale message bundles

Once a default language bundle has been imported, any locale-specific messages are accessed by passing the message bundle to the i18n function.

For example:

import i18n, { Messages } from '@dojo/framework/i18n/i18n';
import bundle from 'nls/main';

i18n(bundle, 'fr').then(function(messages: Messages) {
    console.log(messages.hello); // "Bonjour"
    console.log(messages.goodbye); // "Au revoir"
});

If an unsupported locale is passed to i18n, then the default messages are returned. Further, any messages not provided by the locale-specific bundle will also fall back to their defaults. As such, the default bundle should contain all message keys used by any of the locale-specific bundles.

Alternatively, locale messages can be manually loaded by passing them to setLocaleMessages. This is useful for pre-caching locale-specific messages so that an additional HTTP request is not sent to load them. Locale-specific messages are merged with the default messages, so partial message bundles are acceptable:

import i18n, { setLocaleMessages } from '@dojo/framework/i18n/i18n';
import bundle from 'nls/main';

const partialMessages = { hello: 'Ahoj' };
setLocaleMessages(bundle, partialMessages, 'cz');

i18n(bundle, 'cz').then((messages) => {
    console.log(messages.hello); // "Ahoj"
    console.log(messages.goodbye); // "Goodbye" (defaults are used when not overridden)
});

Once locale dictionaries for a bundle have been loaded, they are cached and can be accessed synchronously via getCachedMessages:

import { getCachedMessages } from '@dojo/framework/i18n/i18n';
import bundle from 'nls/main';

const messages = getCachedMessages(bundle, 'fr');
console.log(messages.hello); // "Bonjour"
console.log(messages.goodbye); // "Au revoir"

getCachedMessages will look up the bundle's supported locales to determine whether the default messages should be returned. Locales are also normalized to their most specific messages. For example, if the 'fr' locale is supported, but 'fr-CA' is not, getCachedMessages will return the messages for the 'fr' locale:

import { getCachedMessages } from '@dojo/framework/i18n/i18n';
import bundle from 'nls/main';

const frenchMessages = getCachedMessages(bundle, 'fr-CA');
console.log(frenchMessages.hello); // "Bonjour"
console.log(frenchMessages.goodbye); // "Au revoir"

const madeUpLocaleMessages = getCachedMessages(bundle, 'made-up-locale');
console.log(madeUpLocaleMessages.hello); // "Hello"
console.log(madeUpLocaleMessages.goodbye); // "Goodbye"

If need be, bundle caches can be cleared with invalidate. If called with a bundle, only the messages for that particular bundle are removed from the cache. Otherwise, all messages are cleared:

import i18n, { getCachedMessages, invalidate } from '@dojo/framework/i18n/main';
import bundle from 'nls/main';

i18n(bundle, 'ar').then(() => {
    invalidate(bundle);
    console.log(getCachedMessages(bundle, 'ar')); // undefined
});

Determining the current locale

The current locale can be accessed via the read-only property i18n.locale, which will always be either the locale set via switchLocale (see below) or the systemLocale.

The systemLocale is also read-only, and its value is determined by the current execution environment in the following manner:

Changing the root locale and observing locale changes

The switchLocale method changes the root locale and notifies all consumers registered with observeLocale, which accepts a function that receives the new locale string as its sole argument. For example, suppose the system locale is en-GB:

import i18n, { observeLocale, switchLocale, systemLocale } from '@dojo/framework/i18n/i18n';
import bundle from 'nls/bundle';

// Register an event listener
observeLocale((locale: string) => {
    // handle locale change...
});

// Change the locale to German. The registered observer's callback will be called
// with the new locale.
switchLocale('de');

// The locale is again switched to German, but since the current root locale is
// already German, registered observers will not be notified.
switchLocale('de');

console.log(i18n.locale); // 'de'
console.log(systemLocale); // 'en-GB' (the system locale does not change with the root locale)