@ basenative/i18n

具有区域设置检测、延迟消息加载和中间件的ICU风格国际化

部分 BaseNative 生态系统——基于信号的web运行时，基于原生HTML。

安装

npm install @basenative/i18n

快速入门

import { createI18n } from '@basenative/i18n';

const i18n = createI18n({
  defaultLocale: 'en',
  messages: {
    en: {
      greeting: 'Hello, {name}!',
      itemCount: '{count, plural, one {# item} other {# items}}',
    },
    es: {
      greeting: 'Hola, {name}!',
      itemCount: '{count, plural, one {# elemento} other {# elementos}}',
    },
  },
});

i18n.t('greeting', { name: 'Alice' }); // "Hello, Alice!"
i18n.t('itemCount', { count: 3 });     // "3 items"

i18n.setLocale('es');
i18n.t('greeting', { name: 'Alice' }); // "Hola, Alice!"

延迟加载

import { createI18n } from '@basenative/i18n';
import { createLoader } from '@basenative/i18n';

const loader = createLoader({
  load: (locale) => import(`./locales/${locale}.json`, { assert: { type: 'json' } })
    .then(m => m.default),
});

const i18n = createI18n({ defaultLocale: 'en' });
await loader.load('fr', i18n);

服务器中间件

import { i18nMiddleware } from '@basenative/i18n';
import { createPipeline } from '@basenative/middleware';

const pipeline = createPipeline()
  .use(i18nMiddleware(i18n));
// ctx.state.locale and ctx.state.t are now available

模板的指令: @t

@basenative/i18n 注册一个 @t 模板指令 @basenative/runtime作为导入这个包的副作用——它在任何地方都可以工作 render() (SSR)或 hydrate() （客户端）运行，没有额外的布线；

<h1 @t="nav.home">Home</h1>

@t 读取 ctx.$i18n -一个i18n实例，来自 createI18n() -从渲染/水合物上下文，并替换元素的文本内容为 i18n.t(key, ctx)． 将整个渲染上下文传递为 params 是指任何 {name}-消息中的样式占位符 (i18n自己的插值语法-请参见 i18n.t() 下面，不是BaseNative的 {{ }}) 是从已经在范围内的同名属性填充的，没有第二个模板语法要学习:

import { createI18n } from '@basenative/i18n';
import { render } from '@basenative/server';

const i18n = createI18n({ defaultLocale: 'en', messages: { en: { 'nav.home': 'Home' } } });
const html = render(template, { ...data, $i18n: i18n });

在客户端上:

import { hydrate } from '@basenative/runtime';

hydrate(root, { ...data, $i18n: i18n });

@t 重新呈现在客户端上，每当 i18n.setLocale() 运行- createI18n() 不会暴露一个 @basenative/runtime 信号，因此该指令订阅 onLocaleChange() 在内部，并从中驱动自己的反应性。

没有 $i18n 在上下文中, @t 保持元素的现有内容不变 (它不会将其留空)，并发出 BN_T_NO_PROVIDER 诊断通过 options.onDiagnostic ——所以 <h1 @t="nav.home">Home</h1> 仍然将“Home”呈现为静态的回退。 message.key 是一个文字键，而不是一个表达式（没有引号）-相同的方式 @feature的标志名称是 (请参阅 @basenative/flags）。

API

createI18n(options?)

创建i18n实例。选项： defaultLocale (默认值: 'en')， messages (区域设置键控对象)。

返回:

• t(key, params?) -翻译消息键与可选的插值参数。
• getLocale() -返回当前语言环境字符串。
• setLocale(locale) -更改活动区域设置。
• addMessages(locale, messages) -将其他消息合并到区域设置中。
• onLocaleChange(fn) -注册在区域设置更改时调用的侦听器。返回一个取消订阅函数。

createLoader(options)

创建一个延迟消息加载程序。选项: load(locale) -异步函数返回一个消息对象。

• loadMessages(locale, i18n) -将区域设置的消息加载到i18n实例中。

i18nMiddleware(i18n, options?)

检测来自的请求区域设置 Accept-Language 页眉和附件 ctx.state.locale 和 ctx.state.t 到请求上下文。

许可证

apache - 2.0