Advanced formatting: CLDR

Loading CLDR data

Given the very large size of the Unicode CLDR data, it is not included as a dependency of @dojo/framework/i18n. Relevant portions of CLDR data must be explicitly loaded when applications require features such as ICU-formatted messages or others provided by @dojo/framework/i18n such as date or number formatters.

Note: Internationalized applications that require simple, unformatted locale-specific messages do not need to concern themselves with loading CLDR data. These applications only need to be configured as per an internationalized Dojo application.

Dojo build system

CLDR data can be loaded from an application’s .dojorc build configuration file via the cldrPaths list within the build-app section.

  • cldrPaths: string[]
    • An array of paths to CLDR JSON files to load. Can be used in conjunction with the locale and supportedLocales options - if a path contains the string {locale}, that file will be loaded for each locale listed in the locale and supportedLocales properties.

For example, with the following configuration, the numbers.json CLDR file will be loaded for all three supported en, es, and fr locales:

.dojorc

  1. {
  2.     "build-app": {
  3.         "locale": "en",
  4.         "supportedLocales": ["es", "fr"],
  5.         "cldrPaths": ["cldr-data/main/{locale}/numbers.json"]
  6.     }
  7. }

Standalone

Outside of the Dojo build system, CLDR data can be loaded via the loadCldrData method exported by @dojo/framework/i18n/cldr/load. loadCldrData accepts an object of CLDR data. All CLDR data must match the format used by the Unicode CLDR JSON files. Supplemental data must be nested within a top-level supplemental object, and locale-specific data must be nested under locale objects within a top-level main object.

For example:

  1. import loadCldrData from '@dojo/framework/i18n/cldr/load';
  3. loadCldrData({
  4.     "supplemental": {
  5.         "likelySubtags": { ... }
  6.     },
  7.     "main": {
  8.         "en": {
  9.             "numbers": { ... }
  10.         }
  11.     }
  12. });

Required CLDR data per feature

Dojo’s i18n module requires the following CLDR data for each particular formatting feature:

For ICU message formatting:

  • supplemental/likelySubtags
  • supplemental/plurals

For date/time formatting:

  • main/{locale}/ca-gregorian
  • main/{locale}/dateFields
  • main/{locale}/numbers
  • main/{locale}/timeZoneNames
  • supplemental/likelySubtags
  • supplemental/numberingSystems
  • supplemental/ordinals
  • supplemental/plurals
  • supplemental/timeData
  • supplemental/weekData

For number/currency formatting:

  • main/{locale}/currencies
  • main/{locale}/numbers
  • supplemental/currencyData
  • supplemental/likelySubtags
  • supplemental/numberingSystems
  • supplemental/ordinals
  • supplemental/plurals

For unit formatting:

  • main/{locale}/numbers
  • main/{locale}/units
  • supplemental/likelySubtags
  • supplemental/numberingSystems
  • supplemental/ordinals
  • supplemental/plurals

Message formatting

Basic token replacement

Dojo’s i18n framework supports ICU message formatting, but this requires CLDR data to be available and is not something that every application requires. As such, if the supplemental/likeSubtags and supplemental/plurals CLDR data are not loaded in the application, then Dojo’s various message formatting methods will perform simple token replacement.

The message formatting examples in the next two subsections will use a message bundle with a guestInfo message as follows:

nls/main.ts

  1. export default {
  2.     messages: {
  3.         guestInfo: '{host} invites {guest} to the party.'
  4.     }
  5. };

With basic token replacement, an object with host and guest properties can be provided to a formatter without the need to load CLDR data.

Replacing tokens in widgets

I18n-aware widgets can use the format function returned from the i18n middleware’s localize method to perform simple token replacement in their messages.

The guestInfo message can be rendered directly via format:

widgets/MyI18nWidget.tsx

  1. import { create, tsx } from '@dojo/framework/core/vdom';
  2. import i18n from '@dojo/framework/core/middleware/I18n';
  4. import nlsBundle from '../nls/main';
  6. const factory = create({ i18n });
  8. export default factory(function MyI18nWidget({ middleware: { i18n } }) {
  9.     const { format } = i18n.localize(nlsBundle);
  11.     return (
  12.         <div>
  13.             {format('guestInfo', {
  14.                 host: 'Margaret Mead',
  15.                 guest: 'Laura Nader'
  16.             })}
  17.         </div>
  18.         // Will render as 'Margaret Mead invites Laura Nader to the party.'
  19.     );
  20. });

Direct token replacement formatting

The i18n module exposes two methods that handle message formatting:

  • formatMessage, which directly returns a formatted message based on its inputs
  • getMessageFormatter, which returns a method dedicated to formatting a single message.

Both of these methods operate on bundle objects, which must first be registered with the i18n ecosystem by passing them to the i18n function.

  1. import i18n, { formatMessage, getMessageFormatter } from '@dojo/framework/i18n/i18n';
  2. import bundle from 'nls/main';
  4. i18n(bundle, 'en').then(() => {
  5.     const formatter = getMessageFormatter(bundle, 'guestInfo', 'en');
  6.     let message = formatter({
  7.         host: 'Margaret Mead',
  8.         guest: 'Laura Nader'
  9.     });
  10.     console.log(message); // "Margaret Mead invites Laura Nader to the party."
  12.     // Note that `formatMessage` is essentially a convenience wrapper around `getMessageFormatter`.
  13.     message = formatMessage(
  14.         bundle,
  15.         'guestInfo',
  16.         {
  17.             host: 'Marshall Sahlins',
  18.             gender: 'male',
  19.             guest: 'Bronisław Malinowski'
  20.         },
  21.         'en'
  22.     );
  23.     console.log(message); // "Marshall Sahlins invites Bronisław Malinowski to the party."
  24. });

ICU message formatting

Note: This feature requires appropriate CLDR data to have been loaded into the application.

@dojo/framework/i18n relies on Globalize.js for ICU message formatting, and as such all of the features offered by Globalize.js are available through @dojo/framework/i18n.

The message formatting examples in the next two subsections will use a message bundle with an updated guestInfo message as follows:

nls/main.ts

  1. export default {
  2.     messages: {
  3.         guestInfo: `{gender, select,
  4.             female {
  5.                 {guestCount, plural, offset:1
  6.                 =0 {{host} does not give a party.}
  7.                 =1 {{host} invites {guest} to her party.}
  8.                 =2 {{host} invites {guest} and one other person to her party.}
  9.                 other {{host} invites {guest} and # other people to her party.}}}
  10.             male {
  11.                 {guestCount, plural, offset:1
  12.                 =0 {{host} does not give a party.}
  13.                 =1 {{host} invites {guest} to his party.}
  14.                 =2 {{host} invites {guest} and one other person to his party.}
  15.                 other {{host} invites {guest} and # other people to his party.}}}
  16.             other {
  17.                 {guestCount, plural, offset:1
  18.                 =0 {{host} does not give a party.}
  19.                 =1 {{host} invites {guest} to their party.}
  20.                 =2 {{host} invites {guest} and one other person to their party.}
  21.                 other {{host} invites {guest} and # other people to their party.}}}}`
  22.     }
  23. };

ICU message formatting in widgets

I18n-aware widgets can use the format function returned from their localizeBundle method to perform ICU message formatting in the same way as for simple token replacement described above.

The ICU-formatted guestInfo message can then be rendered as:

widgets/MyI18nWidget.tsx

  1. import { create, tsx } from '@dojo/framework/core/vdom';
  2. import i18n from '@dojo/framework/core/middleware/I18n';
  4. import nlsBundle from '../nls/main';
  6. const factory = create({ i18n });
  8. export default factory(function MyI18nWidget({ middleware: { i18n } }) {
  9.     const { format } = i18n.localize(nlsBundle);
  11.     return (
  12.         <div>
  13.             {
  14.             format('guestInfo', {
  15.                 host: 'Margaret Mead',
  16.                 gender: 'female',
  17.                 guest: 'Laura Nader',
  18.                 guestCount: 20
  19.             })
  20.             }
  21.         </div>
  22.         ]); // Will render as 'Margaret Mead invites Laura Nader and 19 other people to her party.'
  23.     );
  24. });

Direct ICU message formatting

The ICU-formatted guestInfo message can be converted directly with formatMessage, or getMessageFormatter can be used to generate a function that can be called several times with different options. Note that the formatters created and used by both methods are cached, so there is no performance penalty from compiling the same message multiple times.

Since the Globalize.js formatting methods use message paths rather than the message strings themselves, the @dojo/framework/i18n methods also require that the bundle itself be provided, so its unique identifier can be resolved to a message path within the Globalize.js ecosystem. If an optional locale is provided, then the corresponding locale-specific message will be used. Otherwise, the current locale is assumed.

  1. import i18n, { formatMessage, getMessageFormatter } from '@dojo/framework/i18n/i18n';
  2. import bundle from 'nls/main';
  4. // 1. Load the messages for the locale.
  5. i18n(bundle, 'en').then(() => {
  6.     const message = formatMessage(
  7.         bundle,
  8.         'guestInfo',
  9.         {
  10.             host: 'Margaret Mead',
  11.             gender: 'female',
  12.             guest: 'Laura Nader',
  13.             guestCount: 20
  14.         },
  15.         'en'
  16.     );
  17.     console.log(message); // "Margaret Mead invites Laura Nader and 19 other people to her party."
  19.     const formatter = getMessageFormatter(bundle, 'guestInfo', 'en');
  20.     console.log(
  21.         formatter({
  22.             host: 'Margaret Mead',
  23.             gender: 'female',
  24.             guest: 'Laura Nader',
  25.             guestCount: 20
  26.         })
  27.     ); // "Margaret Mead invites Laura Nader and 19 other people to her party."
  29.     console.log(
  30.         formatter({
  31.             host: 'Marshall Sahlins',
  32.             gender: 'male',
  33.             guest: 'Bronisław Malinowski'
  34.         })
  35.     ); // "Marshall Sahlins invites Bronisław Malinowski to his party."
  36. });

Date and number formatting.

Note: This feature requires appropriate CLDR data to have been loaded into the application.

As with the message formatting capabilities, @dojo/framework/i18n relies on Globalize.js to provide locale-specific formatting for dates, times, currencies, numbers, and units. The formatters themselves are essentially light wrappers around their Globalize.js counterparts, which helps maintain consistency with the Dojo ecosystem and prevents the need to work with the Globalize object directly. Unlike the message formatters, the date, number, and unit formatters are not cached, as they have a more complex set of options. As such, executing the various “get formatter” methods multiple times with the same inputs does not return the exact same function object.

@dojo/framework/i18n groups the various formatters accordingly: date and time formatters (@dojo/framework/i18n/date); number, currency, and pluralization formatters (@dojo/framework/i18n/number); and unit formatters (@dojo/framework/i18n/unit). Each method corresponds to a Globalize.js method (see below), and each method follows the same basic format: the last argument is an optional locale, and the penultimate argument is the method options. If specifying a locale but no options, pass null as the options argument. If no locale is provided, then the current (i18n.locale) is assumed.

  1. import { formatDate, getDateFormatter, formatRelativeTime } from '@dojo/framework/i18n/date';
  2. import { formatCurrency, getCurrencyFormatter } from '@dojo/framework/i18n/number';
  3. import { formatUnit, getUnitFormatter } from '@dojo/framework/i18n/unit';
  5. const date = new Date(1815, 11, 10, 11, 27);
  7. // Assume the current locale is "en"
  8. const enDateFormatter = getDateFormatter({ datetime: 'medium' });
  9. enDateFormatter(date); // Dec 10, 1815, 11:27:00 AM
  10. formatDate(date, { date: 'short' }); // 12/10/15
  12. const frDateFormatter = getDateFormatter({ datetime: 'medium' }, 'fr');
  13. frDateFormatter(date); // 10 déc. 1815 à 11:27:00
  14. formatDate(date, { date: 'short' }, 'fr'); // 10/12/1815
  16. formatRelativeTime(-1, 'week'); // "last week"
  17. formatRelativeTime(-1, 'week', { form: 'short' }); // "last wk."
  18. formatRelativeTime(-3, 'week', null, 'fr'); // "il y a 3 semaines"
  19. formatRelativeTime(-3, 'week', { form: 'short' }, 'fr'); // "il y a 3 sem."
  21. const enCurrencyFormatter = getCurrencyFormatter('USD', { style: 'code' });
  22. enCurrencyFormatter(1234.56); // "1,234.56 USD"
  23. formatCurrency(12345.56, 'USD', { style: 'code' }); // "1,234.56 USD"
  25. const frCurrencyFormatter = getCurrencyFormatter('EUR', { style: 'code' }, 'fr');
  26. frCurrencyFormatter(1234.56); // "1 234,56 EUR"
  27. formatCurrency(12345.56, 'EUR', { style: 'code' }, 'fr'); // "1 234,56 EUR"
  29. const enUnitFormatter = getUnitFormatter('feet', { form: 'narrow' });
  30. enUnitFormatter(5280); // 5,280′
  31. formatUnit(5280, 'feet', { form: 'narrow' }); // 5,280′
  33. const frUnitFormatter = getUnitFormatter('meter', null, 'fr');
  34. frUnitFormatter(1000); // 1 000 mètres'
  35. formatUnit(1000, 'meter', null, 'fr); // 1 000 mètres'

@dojo/framework/i18n/date methods:

@dojo/framework/i18n/number methods:

@dojo/framework/i18n/unit methods: