Internationalizing a Dojo application

i18n widget properties

• locale?: string
  • The locale for the widget.If not specified, then the root application locale or its override is assumed.If specified, the widget's DOM node will have a lang property set to the locale.
• rtl?: boolean
  • An optional flag indicating the widget's text direction. If true, then the underlying DOM node's dir property is set to "rtl". If it is false, then the dir property is set to "ltr". Otherwise, the property is not set.
• i18nBundle?: Bundle<Messages> | Map<Bundle<Messages>, Bundle<Messages>>
  • An optional override for the default language bundle passed to the localizeBundle method. If the override contains a messages object, then it will completely replace the underlying default language bundle that the widget may be using. If the override only contains a locales object, a new bundle will be created with the additional locale loaders specified in the override.

i18n localize() method

Widgets can pass in their default language bundle into the localize method to have the bundle localized appropriately given the widget's locale property.

If the bundle supports the widget's current locale, but those locale-specific messages have not yet been loaded, then a bundle of blank message values is returned. Alternatively, the localize method accepts a second boolean argument, which, when true, causes the default messages to be returned instead of the blank bundle. The widget will be invalidated once the locale-specific messages have been loaded, triggering a re-render with the localized message content.

The object returned by localize contains the following properties and methods:

• messages
  • An object containing the localized message key-value pairs. If the messages have not yet loaded, then messages will be either a blank bundle or the default messages, depending upon how localize was called.
• isPlaceholder
  • A boolean property indicating whether the returned messages are the actual locale-specific messages (false) or just the placeholders used while waiting for the localized messages to finish loading (true). This is useful to prevent the widget from rendering at all if localized messages have not yet loaded.
• format(key: string, replacements: { [key: string]: string })
  • A method that accepts a message key as its first argument and an object of replacement values as its second. For example, if the bundle contains greeting: 'Hello, {name}!', then calling format('greeting', { name: 'World' }) would return 'Hello, World!'.

An example of using all features returned by localize:

nls/en/MyI18nWidget.ts

export default {
    messages: {
        hello: 'Welcome to the shop',
        purchaseItems: 'Please confirm your purchase',
        itemCount: 'Purchase {count} items'
    }
};

widgets/MyI18nWidget.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import i18n from '@dojo/framework/core/middleware/i18n';
import Label from '@dojo/widgets/label';
import Button from '@dojo/widgets/button';

import greetingsBundle from '../nls/en/MyI18nWidget';

const factory = create({ i18n });

export default factory(function MyI18nWidget({ middleware: { i18n } }) {
    // Load the "greetings" messages for the current locale. If the locale-specific
    // messages have not been loaded yet, then the default messages are returned,
    // and the widget will be invalidated once the locale-specific messages have
    // loaded.
    const { format, isPlaceholder, messages } = i18n.localize(greetingsBundle);

    // In many cases it makes sense to postpone rendering until the locale-specific messages have loaded,
    // which can be accomplished by returning early if `isPlaceholder` is `true`.
    if (isPlaceholder) {
        return;
    }

    return v('div', { title: messages.hello }, [
        w(Label, {}, [
            // Passing a message string to a child widget.
            messages.purchaseItems
        ]),
        w(Button, {}, [
            // Passing a formatted message string to a child widget.
            format('itemCount', { count: 2 })
        ])
    ]);
});

Note that with this pattern it is possible for a widget to obtain its messages from multiple bundles. When favoring simplicity, however, it is recommend that widgets are limited to a single bundle wherever possible.

I18nMixin for class-based widgets

Individual class-based widgets can be internationalized by adding the I18nMixin mixin from @dojo/framework/core/mixins/I18n. This mixin adds the same optional i18n-related widget properties as the i18n middleware, and provides a localizeBundle method which is used to localize an imported message bundle to the widget's current locale.

export default {
    messages: {
        hello: 'Welcome to the shop',
        purchaseItems: 'Please confirm your purchase',
        itemCount: 'Purchase {count} items'
    }
};

import WidgetBase from '@dojo/framework/core/WidgetBase';
import { v, w } from '@dojo/framework/core/vdom';
import I18nMixin from '@dojo/framework/core/mixins/I18n';
import Label from '@dojo/widgets/label';
import Button from '@dojo/widgets/button';

import greetingsBundle from '../nls/en/MyI18nWidget';

export default class MyI18nWidget extends I18nMixin(WidgetBase) {
    render() {
        // Load the "greetings" messages for the current locale. If the locale-specific
        // messages have not been loaded yet, then the default messages are returned,
        // and the widget will be invalidated once the locale-specific messages have
        // loaded.
        const { format, isPlaceholder, messages } = this.localizeBundle(greetingsBundle);

        // In many cases it makes sense to postpone rendering until the locale-specific messages have loaded,
        // which can be accomplished by returning early if `isPlaceholder` is `true`.
        if (isPlaceholder) {
            return;
        }

        return v('div', { title: messages.hello }, [
            w(Label, {}, [
                // Passing a message string to a child widget.
                messages.purchaseItems
            ]),
            w(Button, {}, [
                // Passing a formatted message string to a child widget.
                format('itemCount', { count: 2 })
            ])
        ]);
    }
}

Example usage

The following example shows an i18n-aware widget that renders two buttons that allow switching the application locale between English and French.

import { create, tsx } from '@dojo/framework/core/vdom';
import i18n from '@dojo/framework/core/middleware/I18n';

import nlsBundle from '../nls/main';

const factory = create({ i18n });

export default factory(function LocaleChanger({ middleware: { i18n } }) {
    const { messages } = localize(nlsBundle);
    return (
        <div>
            <button
                onclick={() => {
                    i18n.set({ locale: 'en' });
                }}
            >
                English
            </button>
            <button
                onclick={() => {
                    i18n.set({ locale: 'fr' });
                }}
            >
                French
            </button>
            <div>{messages.greetings}</div>
        </div>
    );
});