国际化 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>
	);
});