Advanced formatting: CLDR

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

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 MyI18nWidget({ middleware: { i18n } }) {
    const { format } = i18n.localize(nlsBundle);

    return (
        <div>
            {format('guestInfo', {
                host: 'Margaret Mead',
                guest: 'Laura Nader'
            })}
        </div>
        // Will render as 'Margaret Mead invites Laura Nader to the party.'
    );
});

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.

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

i18n(bundle, 'en').then(() => {
    const formatter = getMessageFormatter(bundle, 'guestInfo', 'en');
    let message = formatter({
        host: 'Margaret Mead',
        guest: 'Laura Nader'
    });
    console.log(message); // "Margaret Mead invites Laura Nader to the party."

    // Note that `formatMessage` is essentially a convenience wrapper around `getMessageFormatter`.
    message = formatMessage(
        bundle,
        'guestInfo',
        {
            host: 'Marshall Sahlins',
            gender: 'male',
            guest: 'Bronisław Malinowski'
        },
        'en'
    );
    console.log(message); // "Marshall Sahlins invites Bronisław Malinowski to the party."
});

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

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 MyI18nWidget({ middleware: { i18n } }) {
    const { format } = i18n.localize(nlsBundle);

    return (
        <div>
            {
            format('guestInfo', {
                host: 'Margaret Mead',
                gender: 'female',
                guest: 'Laura Nader',
                guestCount: 20
            })
            }
        </div>
        ]); // Will render as 'Margaret Mead invites Laura Nader and 19 other people to her party.'
    );
});

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.

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

// 1. Load the messages for the locale.
i18n(bundle, 'en').then(() => {
    const message = formatMessage(
        bundle,
        'guestInfo',
        {
            host: 'Margaret Mead',
            gender: 'female',
            guest: 'Laura Nader',
            guestCount: 20
        },
        'en'
    );
    console.log(message); // "Margaret Mead invites Laura Nader and 19 other people to her party."

    const formatter = getMessageFormatter(bundle, 'guestInfo', 'en');
    console.log(
        formatter({
            host: 'Margaret Mead',
            gender: 'female',
            guest: 'Laura Nader',
            guestCount: 20
        })
    ); // "Margaret Mead invites Laura Nader and 19 other people to her party."

    console.log(
        formatter({
            host: 'Marshall Sahlins',
            gender: 'male',
            guest: 'Bronisław Malinowski'
        })
    ); // "Marshall Sahlins invites Bronisław Malinowski to his party."
});