国际化 Dojo 应用程序

i18n 小部件属性

• locale?: 字符串
  • 小部件的语言环境。如果未指定，则假定 根应用程序语言环境 或 其覆盖。如果指定，则小部件的 DOM 节点将具有设置为语言环境的 lang 属性。
• rtl?: 布尔值
  • 一个可选标志，指示小部件的文本方向。如果为 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 })
  • 一个方法，接受消息键作为其第一个参数，并接受替换值的数组作为其第二个参数。例如，如果包包含 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 混合器来国际化单个面向类的小部件。此混合器添加了与 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>
	);
});