Internationalizing a Dojo application

Configuring supported application locales

An internationalized application should specify all its supported locales within its .dojorc build configuration file. One locale should be designated as the primary/default locale for the application, with the remainder of the supported locales as secondary options that can be activated when required. This is done via the locale property and supportedLocales list within the build-app section.

Note: Since the various formatters and parsers rely on locale-specific CLDR data, most of the functionality provided by @dojo/framework/i18n requires at least a locale to be set in the .dojorc in order to function properly. For example, if no default locale is specified, then only the default bundle messages will be returned and ICU message formatting will be disabled.

• locale: string
  • The primary locale supported by the application. That is, the default language that will be used if an override locale is not specified.
• supportedLocales: string[]
  • A list of additional locales that the application supports. These locales need to be activated to override the default locale, either implicitly through an application user's language setting when running client-side, the process' or host's language setting when running server-side, or explicitly within the application itself.

For example, with the following configuration, an application specifies that its default locale is English (en), and that it supports Spanish (es) and French (fr) as additional locale choices:

.dojorc

{
	"build-app": {
		"locale": "en",
		"supportedLocales": ["es", "fr"]
	}
}

Creating i18n-aware widgets

Individual widgets can be internationalized by using the i18n middleware from @dojo/framework/core/middleware/i18n. Using the middleware adds some optional i18n-related properties to the widget property interface. The API for the i18n middleware includes a method, localize(bundle) to get the localized nls values given a message bundle and two methods that can be used to get and set the application's locale details.

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

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 })
		])
	]);
});

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 })
			])
		]);
	}
}

Providing locale data to i18n-aware widgets

Locale details also need to be managed via a Dojo registry when applications use i18n-aware class-based widgets (specifically, those that use I18nMixin). This applies to any such widgets contained within the application itself or as part of an external dependency - including any widgets used from Dojo's @dojo/widgets suite. Locale data is injected into all such widgets through the Dojo registry system; these widgets will be invalidated and re-rendered with updated locale data when the application locale is changed.

This mechanism is enabled through registerI18nInjector, a convenience method provided by @dojo/framework/core/mixins/I18n. Calling this method will register the i18n injector within a specific registry instance. Typically this is done at application bootstrap, where the i18n injector is registered against the global registry passed to the renderer.mount() method.

main.ts

import renderer from '@dojo/framework/core/vdom';
import { w } from '@dojo/framework/core/vdom';
import Registry from '@dojo/framework/core/Registry';
import { registerI18nInjector } from '@dojo/framework/core/mixins/I18n';

import App from './App';

const registry = new Registry();
registerI18nInjector({ locale: 'us', rtl: false }, registry);

const r = renderer(() => w(App, {}));
r.mount({ registry });

Changing locales

The i18n middleware can be used to change the application's locale. Calling i18n.set({ locale: string, rtl: boolean }); will propagate the new locale to all widgets that are using the i18n middleware, as well as any using I18nMixin (assuming registerI18nInjector has previously been setup in the application).

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>
	);
});

Overriding locales and bundles per-widget

Widgets that use either the i18n middleware or I18nMixin can have their i18n widget properties overridden when instantiated by a parent. This can be useful when rendering several widgets with different locales in a single application (that is, using multiple locales within one application), as well as to override the set of messages a third-party widget may be using and align them within the context of your application.

Each i18n-aware widget can have its own independent locale by providing a locale widget property. If no locale property is set, then the default locale is assumed.

The widget's default bundle can also be replaced by passing an i18nBundle widget property. Dojo recommends against using multiple bundles in the same widget, but there may be times when an application needs to consume a third-party widget that does make use of more than one bundle. As such, i18nBundle can also be a Map of default bundles to override bundles.

An example of overriding bundles within child widgets:

import { Bundle } from '@dojo/framework/i18n/i18n';

// A complete bundle to replace WidgetA's message bundle
import overrideBundleForWidgetA from './nls/widgetA';

// Bundles for WidgetB
import widgetB1 from 'third-party/nls/widgetB1';
import overrideBundleForWidgetB from './nls/widgetB';

// WidgetB uses multiple bundles, but only `thirdy-party/nls/widgetB1` needs to be overridden
const overrideMapForWidgetB = new Map<Bundle<any>, Bundle<any>>();
map.set(widgetB1, overrideBundleForWidgetB);

export class MyWidget extends WidgetBase {
	protected render() {
		return [
			w(WidgetA, {
				i18nBundle: overrideBundleForWidgetA
			}),
			w(WidgetB, {
				i18nBundle: overrideMapForWidgetB
			}),
			// This example partially overrides the overrideKey value in the widgetB1 bundle
			w(WidgetC, {
				i18nBundle: { ...widgetB1, { overrideKey: 'abc' }}
			})
		];
	}
}

Default locale

The locale that an i18n-aware widget will use is determined in the following order until a value is found, depending on which i18n features an application makes use of: