# @basenative/i18n 中文文档

规范地址：https://npmcn.com/package/%40basenative/i18n/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:17.900Z
中文译文更新时间：2026-10-31T16:17:06.375Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basenative/i18n
原文对照：https://npmcn.com/package/%40basenative/i18n/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/i18n#readme
源码仓库：https://github.com/DuganLabs/BaseNative

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.9 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-20T05:27:47.326Z
- 最新版本发布：2026-10-31T13:47:17.545Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

ICU消息格式化、语言环境检测和@t模板指令

## 安装

```sh
npm install @basenative/i18n
```

也可以使用：`pnpm add @basenative/i18n`、`yarn add @basenative/i18n`、`bun add @basenative/i18n`

## README

# @ basenative/i18n

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

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/i18n
```

## 快速入门

```js
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!"
```

## 延迟加载

```js
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);
```

## 服务器中间件

```js
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()` （客户端）运行，没有额外的布线；

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

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

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

在客户端上:

```js
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

## 常见问题

### @basenative/i18n 是什么？

ICU消息格式化、语言环境检测和@t模板指令

### 如何安装 @basenative/i18n？

在项目目录运行 npm install @basenative/i18n，或使用 pnpm add / yarn add / bun add。

### @basenative/i18n 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basenative/i18n 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/i18n 可以商用吗？

@basenative/i18n 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/i18n 还在维护吗？

最新版本 3\.0\.0 发布于 2026/10/31（2 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。