Working with message bundles

Bundle default language

Each message bundle has its own set of supported language translations. One language within the set is required to act as the default module for the rest of the bundle. The default language module acts as the primary import/reference to the bundle, and serves two main requirements:

• Provides a comprehensive set of message keys and their content (represented in the default language) that are used as a fallback if other languages within the bundle do not provide overrides for a given key
• Lists the bundle's other supported languages, as well as the mechanism to load the set of messages from each supported language's module

TypeScript structure

Every language within a bundle is a TypeScript module, and is required to export a default object representing a map of message keys to their translated values within the particular language.

For example, a French language module within a bundle:

nls/fr/main.ts

export default {
	hello: 'Bonjour',
	goodbye: 'Au revoir'
};

export default {
	locales: {
		fr: () => import('./fr/main'),
		ar: () => import('./ar/main'),
		ja: () => import('./ja/main')
	},
	messages: {
		hello: 'Hello',
		goodbye: 'Goodbye'
	}
};

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

Importing and using bundles

The default language module for a bundle is imported like any other TypeScript module into each widget that requires use of the set of messages contained within the bundle.

For example, given a default bundle:

nls/en/MyI18nWidget.ts

export default {
	messages: {
		hello: 'Hello',
		welcome: 'Welcome to your application'
	}
};

This can be imported and referenced within a widget such as:

widgets/MyI18nWidget.tsx

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

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

const factory = create({ i18n });

export default factory(function MyI18nWidget({ middleware: { i18n } }) {
	const { messages } = i18n.localize(myWidgetMessageBundle);

	return <div title={messages.hello}>{messages.welcome}</div>;
});

As this example widget loads its messages through the i18n middleware's .localize method, it will continue to work as new language translations are added and referenced within the bundle's nls/en/MyI18nWidget.ts default language module. Users will see localized messages from MyI18nWidget instances if a message set for their currently configured language is available.

Applications that want to override user default languages and allow changing locales within the application itself require additional setup, covered in Internationalizing a Dojo application.

Lazy vs. static loading

It is preferable to use functions in the default language's locales map to load other language translation modules, as this allows locale message bundles to be lazily loaded, only if required.

Some applications may however prefer certain languages to be statically loaded along with the bundle's default language module, and can do so by returning a compatible object structure directly.

An example of both types of loading within a bundle:

import fr from './fr/main';

export default {
	locales: {
		// Locale providers can load translations lazily...
		ar: () => import('./ar/main'),
		'ar-JO': () => import('./ar-JO/main'),

		// ... or return references directly.
		fr
	},
	// Default/fallback messages
	messages: {
		hello: 'Hello',
		goodbye: 'Goodbye'
	}
};