国际化 Dojo 应用程序

i18n 部件属性

• locale?: string
  • 部件的区域设置。如果没有指定，则使用应用程序根设置 或重写的区域。如果指定，则部件 DOM 节点的 lang 属性会被设置为该区域。
• rtl?: boolean
  • 一个可选标记，指定部件的文本方向。如果值为 true，则部件底层 DOM 节点的 dir 属性设置为 "rtl"。如果值为 false，则 dir 属性设置为 "ltr"。否则，不设置该属性。
• i18nBundle?: Bundle<Messages> | Map<Bundle<Messages>, Bundle<Messages>>
  • 一个可选的覆写，传给 localizeBundle 方法的默认语言包。如果覆写包含 messages 对象，那么它将完全替换部件使用的默认语言包。如果覆写仅包含一个 locales 对象，则将使用覆盖中指定的其他本地化加载器来加载新创建的包。

i18n 的 localize() 方法

部件可以将默认语言包传给 localize 方法，以便根据部件的 locale 属性获取对应的本地化包。

如果包支持部件当前设置的区域，但尚未加载这些特定区域的消息，则会返回一个消息都为空字符串的包。或者，为 localize 方法传入第二个布尔类型的参数，当值为 true 时，则会返回默认的消息，而不返回空包。当特定语言的消息加载完成，部件会失效，然后使用本地化的消息内容重新渲染。

localize 返回的对象包含以下属性和方法：

• messages
  • 一个对象，包含本地化消息的键值对。如果此消息尚未加载，则 messages 的值是空包或者默认的消息，这取决于调用 localize 的方式。
• isPlaceholder
  • 一个布尔属性，指出返回的消息是实际的特定区域的消息（false），还是只是等待本地化消息完成加载时使用的占位符（true）。如果本地化消息尚未加载，则要避免渲染部件。
• format(key: string, replacements: { [key: string]: string })
  • 一个方法，第一个参数是消息的 key，第二个参数是用于替换的值。例如，如果包中包含 greeting: 'Hello, {name}!'，则调用 format('greeting', { name: 'World'}) 将返回 'Hello, World!'。

以下示例使用了 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 })
        ])
    ]);
});

注意，这种模式支持部件从多个包中获取消息。但是，简洁起见，推荐每个部件单独使用各自的消息包。

基于类的部件使用 I18nMixin

通过混入 @dojo/framework/core/mixins/I18n 中的 I18nMixin，可国际化单个基于类的部件。这个 Mixin 将与 i18n 中间件相同的 i18n 相关属性添加到部件属性中，并且提供了一个 localizeBundle 方法，将导入的消息包与部件当前设置的区域关联。

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

用法示例

下面的示例展示了一个支持 i18n 的部件，它会渲染两个按钮，用于在英语和法语之间切换应用程序的区域。

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