# @cybernetex/kbn-i18n 中文文档

规范地址：https://npmcn.com/package/%40cybernetex/kbn-i18n/

版本：1\.0\.0
npm 元数据更新时间：2022-04-05T02:25:33.815Z
中文译文更新时间：2026-11-11T06:42:48.320Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cybernetex/kbn-i18n
原文对照：https://npmcn.com/package/%40cybernetex/kbn-i18n/?lang=original

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

- 包体积（解压后）：335 kB，104 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2019-08-17T01:42:50.168Z
- 最新版本发布：2019-08-17T01:42:50.497Z
- 近 30 天下载量：7248（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

Kibana依赖于多个UI框架(ReactJS和AngularJS),需要在不同环境中(浏览器和NodeJS)本地化. 国际化引擎是框架不可知并可消耗于基巴纳的所有地区(ReactJS,AngularJS和NodeJS)

## 安装

```sh
npm install @cybernetex/kbn-i18n
```

也可以使用：`pnpm add @cybernetex/kbn-i18n`、`yarn add @cybernetex/kbn-i18n`、`bun add @cybernetex/kbn-i18n`

## README

# I18n 时

Kibana依赖于几个UI框架(ReactJS和AngularJS)和 需要在不同环境中本地化(浏览器和节点JS). 国际化引擎具有框架不可知性和消耗性 kibana的所有部分(ReactJS,AngularJS和NodeJS). 为了简化 在UI框架中的国际化,额外的抽象是: 围绕I18n引擎建造: `react-intl` 用于反应和自定义 angularJS 组件. [反应- 插入](https://github.com/yahoo/react-intl) 围绕 [内存信息格式](https://github.com/yahoo/intl-messageformat), (中文(简体) ), 因此 React 和 AngularJS 框架都使用相同的引擎和相同的 消息语法.

## 本地化文件

本地化文件为JSON文件.

使用注释可以帮助理解应用程序的哪个部分 用于本地化密钥。 还有 `namespaces` 用于简化消息位置搜索。 例如,如果 我们将翻译 `/management/sections/objects/_objects.html` 文件,我们应该使用这样的消息路径 : `'management.objects.objectsTitle'`。 。 。 .

每个 Kibana 插件有一个单独的文件夹, 翻译文件位于

```
{path/to/plugin}/translations/{locale}.json
```

地点 `locale` 实值 [ISO 639 语言代码](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)。 。 。 .

例如:

```
src/legacy/core_plugins/kibana/translations/fr.json
```

引擎扫描 `x-pack/legacy/plugins/*/translations`, (中文(简体) ), `src/core_plugins/*/translations`, (中文(简体) ), `plugins/*/translations` 财务报告和审定财务报表 `src/legacy/ui/translations` 初始化文件夹,所以不需要注册翻译文件.

引擎使用一个 `config/kibana.yml` 用于本地化解析进程的文件。 如果语言是 通过 `i18n.locale` 选项在 `config/kibana.yml` 然后它将成为基地 语言,否则 i18n 引擎将返回 `en`编辑 `en` 语言也将被使用 如果无法为基础非英语语言找到翻译.

我们的技术要求之一是模板中有默认信息 自己,那些留言将永远是英文, 所以我们不必保留 `en.json` 文件在仓库中。 我们可以从 `defaultMessage`编号 定义内行.

**说明:** 定义于 `i18n.locale` 用于翻译文件的文件应 完全匹配,例如. `i18n.locale: zh` 财务报告和审定财务报表 `.../translations/zh-CN.json` 无法匹配 将使用默认的英文翻译,但 `i18n.locale: zh-CN` 财务报告和审定财务报表`.../translations/zh-CN.json` 或者说 `i18n.locale: zh` 财务报告和审定财务报表 `.../translations/zh.json` 将如所预期的那样发挥作用.

**说明:** 地方应该像 `zh-CN` 地点 `zh` - 小写双字母或三字母ISO-639代码 财务报告和审定财务报表 `CN` - 大写双字母ISO-3166代码(可选). [ISO-639号标准](https://www.iso.org/iso-639-language-codes.html) 财务报告和审定财务报表 [ISO-3166 标准](https://www.iso.org/iso-3166-country-codes.html) 代码应当与 `-` 字符键.

## I18n 发动机

I18n 引擎是平台不可知抽象,有助于提供地产 提供直接翻译的方法.

以下是这个引擎曝光的公众API:

-   `addMessages(messages: Map<string, string>, [locale: string])` - 提供一种登记方式 用引擎翻译
-   `getMessages()` - 返回当前语言的信息
-   `setLocale(locale: string)` - 告诉引擎使用哪一种语言 语言密钥
-   `getLocale()` - 返回当前区域
-   `setDefaultLocale(locale: string)` - 告诉图书馆哪一种语言会退缩 缺少翻译时
-   `getDefaultLocale()` - 返回默认区域
-   `setFormats(formats: object)` - 提供一套选择 基础物. 详细解释见下文一节
-   `getFormats()` - 返回当前格式
-   `getRegisteredLocales()` - 返回有翻译的语境序列
-   `translate(id: string, { values: object, defaultMessage: string, description: string })` – 说吧 – 由 id 翻译消息 . `description` 是将提取的可选上下文注释 i18n 工具,并添加为翻译消息旁边的评论 `defaultMessages.json`。 。 。 .
-   `init(messages: Map<string, string>)` - 启动引擎

#### I18n发动机内部

引擎使用 ICU Message 语法, 并对所有的 QQR 语言工作 定义了复数化规则。 这是围绕 `intl-messageformat` 软件包 它暴露了 `IntlMessageFormat` 课。 向构建器提供信件 作为字符串消息,或预分解的 AST 对象.

```js
import IntlMessageFormat from 'intl-messageformat';

const msg = new IntlMessageFormat(message, locales, [formats]);
```

字符串 `message` 解析,然后在内部存储 优化用于 `format()` 方法 生成向用户显示的格式化字符串.

```js
const output = msg.format(values);
```

`formats` 参数在 `IntlMessageFormat` 构造器允许格式化编号 使用 `Intl.NumberFormat` 财务报告和审定财务报表 `Intl.DateTimeFormat`, (中文(简体) ), 页:1.

```js
const msg = new IntlMessageFormat('The price is: {price, number, USD}', 'en-US', {
  number: {
    USD: {
      style   : 'currency',
      currency: 'USD',
    },
  },
});

const output = msg.format({ price: 100 });

console.log(output); // => "The price is: $100.00"
```

在这个例子中,我们正在定义一个美元数字格式样式 基础 `Intl.NumberFormat` 作为选择. [给](https://github.com/yahoo/intl-messageformat/blob/master/src/core.js#L62) 您可以找到用作格式原型的默认格式选项 提供给建筑师.

创建实例 `IntlMessageFormat` 很贵的. [格式化缓存](https://github.com/yahoo/intl-format-cache) 库只是为了更容易创建缓存格式 用于协助其再利用的特定类型的实例。 在 头罩,此软件包根据所通过参数创建缓存密钥 给纪念建筑师.

```js
import memoizeIntlConstructor from 'intl-format-cache';

const getMessageFormat = memoizeIntlConstructor(IntlMessageFormat);
```

## 香草联署材料

`Intl-messageformat` 软件包假设: [输入](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) 全球对象存在于运行时. `Intl` 存在于所有现代 浏览器和Node.js 0.10+. 为装入i18n 引擎 在节点.js,我们应该简单地 `import` 此模块(在节点.js中 [数据](https://github.com/yahoo/intl-messageformat/tree/master/dist/locale-data) 与图书馆一起装入所有200+语言),并通过翻译 信件输入 `init` 方法 :

```js
import { i18n } from '@kbn/i18n';

i18n.init(messages);
```

一个常见的用法是将一串常数国际化。 这个 我们如何做到这一点的例子:

```js
import { i18n } from '@kbn/i18n';

export const HELLO_WORLD = i18n.translate('hello.wonderful.world', {
  defaultMessage: 'Greetings, planet Earth!',
});
```

还有一个有参数的例子:

```js
import { i18n } from '@kbn/i18n';

export function getGreetingMessage(userName) {
  return i18n.translate('hello.wonderful.world', {
    defaultMessage: 'Greetings, {name}!',
    values: { name: userName },
    description: 'This is greeting message for main screen.'
  });
}
```

我们还可以使用i18n引擎暴露出的所有方法 (见 [I18n 发动机](https://npmcn.com/package/%40cybernetex/kbn-i18n/#readme-i18n-engine) (详见上文一节).

## 反应

[反应- 插入](https://github.com/yahoo/react-intl) 库用于内部化 反应部分应用. 它提供了反应组件和一个格式化的 API 日期、数字和字符串,包括复数化和处理翻译.

React Intl使用提供商模式将一个i18n上下文范围到一棵组件树上. `IntlProvider` 组件用于为树设置 i18n 上下文。 之后,我们 能够使用 `FormattedMessage` 用于翻译信件的组件. `IntlProvider` 应当将反应app的根组件(每个反应渲染方法的内侧)包起来.

为了翻译信件,我们需要使用 `I18nProvider` 组成部分 在引擎盖下使用I18n引擎:

```js
import React from 'react';
import ReactDOM from 'react-dom';
import { I18nProvider } from '@kbn/i18n/react';

ReactDOM.render(
  <I18nProvider>
    <RootComponent>
      ...
    </RootComponent>
  </I18nProvider>,
  document.getElementById('container')
);
```

之后,我们可以使用 `FormattedMessage` 内部组件 `RootComponent`数字 :

```jsx
import React, { Component } from 'react';
import { FormattedMessage } from '@kbn/i18n/react';

class RootComponent extends Component {
  constructor(props) {
    super(props);

    this.state = {
      name: 'Eric',
      unreadCount: 1000,
    };
  }

  render() {
    const {
      name,
      unreadCount,
    } = this.state;

    return (
      <p>
        <FormattedMessage
          id="welcome"
          defaultMessage="Hello {name}, you have {unreadCount, number} {unreadCount, plural,
            one {message}
            other {messages}
          }"
          values={{name: <b>{name}</b>, unreadCount}}
        />
        ...
      </p>
    );
  }
}
```

可以选择通过 `description` 输入 `FormattedMessage` 组件. 此道具是可选的上下文注释,将由 i18n 工具取出 ,并添加到翻译信件旁边的评论 `defaultMessages.json`

**注:** 尽可能减少多重性的机会 `I18nProvider` react 树中的组件,请尝试使用 `I18nProvider` 仅可以包裹您渲染的最顶端组件, 例如, 传递给 `reactDirective` 或者说 `ReactDOM.render`。 。 。 .

### 格式调整

`FormattedRelative` 期望若干属性( 更多阅读) [这里](https://github.com/yahoo/react-intl/wiki/Components#formattedrelative),包括:

-   `value` 可以被分析为日期,
-   `formats` 应该是其中之一 `'years' | 'months' | 'days' | 'hours' | 'minutes' | 'seconds'` (此选项配置于 [`formats.ts`](https://npmcn.com/package/%40cybernetex/kbn-i18n/src/core/formats.ts)(中文(简体) )
-   包括:.

若为 `formats` 不提供, 则将自动选择 :  
`x seconds ago` 页:1 `x < 60`, (中文(简体) ), `1 minute ago` 页:1 `60 <= x < 120`等 (中文(简体) ).

```jsx
<FormattedRelative
  value={Date.now() - 90000}
  format="seconds"
/>
```

初步结果: `90 seconds ago`

```jsx
<FormattedRelative
  value={Date.now() - 90000}
/>
```

初步结果: `1 minute ago`

### React 中的属性翻译

长期计划是依靠 `FormattedMessage` 财务报告和审定财务报表 `i18n.translate()` 通过静态导入 `i18n` 从 `@kbn/i18n` 软件包. **避免使用 `injectI18n` 并依赖 `i18n.translate()` 换句话说.**

React 包装器提供了一种能力,通过它使用道具将强制格式的API注入React 组件 `injectI18n` 高阶组件。 当您的 React 组件需要将数据格式化为一个不适合 React 元素的字符串值时,应当使用此功能; 例如, a `title` 或者说 `aria` 属性。 为了使用它,你应该用 `injectI18n` 高阶组件。 将通过以下方式向包裹的组件提供格式化的API: `props.intl`。 。 。 .

将组件作为纯函数 :

```js
import React from 'react';
import { injectI18n, intlShape } from '@kbn/i18n/react';

export const MyComponent = injectI18n({ intl }) => (
  <input
    type="text"
    placeholder={intl.formatMessage(
      {
        id: 'welcome',
        defaultMessage: 'Hello {name}, you have {unreadCount, number}\
{unreadCount, plural, one {message} other {messages}}',
        description: 'Message description',
      },
      { name, unreadCount }
    )}
  />
));

MyComponent.WrappedComponent.propTypes = {
  intl: intlShape.isRequired,
};
```

作为类反应组件 :

```js
import React from 'react';
import { injectI18n, intlShape } from '@kbn/i18n/react';

export const MyComponent = injectI18n(
  class MyComponent extends React.Component {
    static propTypes = {
      intl: intlShape.isRequired,
    };

    render() {
      const { intl } = this.props;

      return (
        <input
          type="text"
          placeholder={intl.formatMessage({
            id: 'kbn.management.objects.searchPlaceholder',
            defaultMessage: 'Search',
          })}
        />
      );
    }
  }
);
```

## 角 JS 语言

长期计划是依靠 `i18n.translate()` 通过静态导入 `i18n` 从 `@kbn/i18n` 软件包. **避免使用 `i18n` 过滤器和 `i18n` 服务注入控制器、指令、服务.**

AngularJS 包装器有4个实体: 翻译 `provider`, (中文(简体) ), `service`, (中文(简体) ), `directive` 财务报告和审定财务报表 `filter`。指令和过滤器都使用翻译 `service` 引擎盖下装有i18n引擎.

翻译 `provider` 用于 `service` 配置和 有下列方法:

-   `addMessages(messages: Map<string, string>, [locale: string])` - 提供一种登记方式 图书馆翻译
-   `setLocale(locale: string)` - 告诉图书馆使用哪一种语言 语言密钥
-   `getLocale()` - 返回当前区域
-   `setDefaultLocale(locale: string)` - 告诉图书馆哪一种语言会退缩 缺少翻译时
-   `getDefaultLocale()` - 返回默认区域
-   `setFormats(formats: object)` - 提供一套关于基础物的选项
-   `getFormats()` - 返回当前格式
-   `getRegisteredLocales()` - 返回有翻译的语境序列
-   `init(messages: Map<string, string>)` - 启动引擎

翻译 `service` 只提供一种方法:

-   `i18n(id: string, { values: object, defaultMessage: string, description: string })` – 说吧 – 由 id 翻译信件

翻译 `filter` 用于属性翻译并有 下列语法:

```
{{ ::'translationId' | i18n: { values: object, defaultMessage: string, description: string } }}
```

地点:

-   `translationId` - 待翻译的id
-   `values` - 转换的数值
-   `defaultMessage` - 除非翻译成功,否则将使用(最后文本) 英文的回落,用于生成 `en.json`(中文(简体) )
-   `description` - 由 i18n 工具提取的可选上下文注释 ,并添加到翻译信件旁边的评论 `defaultMessages.json`

翻译 `directive` 语法如下:

```html
<ANY
  i18n-id="{string}"
  i18n-default-message="{string}"
  [i18n-values="{object}"]
  [i18n-description="{string}"]
></ANY>
```

地点:

-   `i18n-id` - 待翻译的id
-   `i18n-default-message` - 除非翻译成功,否则将使用
-   `i18n-values` - 转换的数值
-   `i18n-description` - 由 i18n 工具提取的可选上下文注释 ,并添加到翻译信件旁边的评论 `defaultMessages.json`

如果 HTML 渲染为 `i18n-values` 中需要值键 `i18n-values` 对象 应该有 `html_` 前缀。 否则,该值将插入到信件中,而不包含 HTML 渲染.  
示例

```html
<p
  i18n-id="namespace.id"
  i18n-default-message="Text with an emphasized {text}."
  i18n-values="{
    html_text: '<em>text</em>',
  }"
></p>
```

角质 `I18n` 模块被放置到 `autoload` 模块,所以这将是 自动装入 。 之后,我们可以在Angular模板中使用i18n指令:

```html
<span
  i18n-id="welcome"
  i18n-default-message="Hello!"
></span>
```

为了在AngularJS中翻译属性,我们应该使用 `i18nFilter`数字 :

```html
<input
  type="text"
  placeholder="{{ ::'kbn.management.objects.searchAriaLabel' | i18n: {
    defaultMessage: 'Search { title } Object',
    values: { title }
  } }}"
>
```

## I18n 工具

为了简化本地化进程,实施了一些额外的工具:

-   用于校验所有翻译的工具有可转换字符串,并从模板中提取默认信件
-   用于校验翻译文件并将其整合到 Kibana 的工具

[I18n 工具文档](https://npmcn.com/package/src/dev/i18n/README.md)

## 常见问题

### @cybernetex/kbn-i18n 是什么？

Kibana依赖于多个UI框架\(ReactJS和AngularJS\),需要在不同环境中\(浏览器和NodeJS\)本地化\. 国际化引擎是框架不可知并可消耗于基巴纳的所有地区\(ReactJS,AngularJS和NodeJS\)

### 如何安装 @cybernetex/kbn-i18n？

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

### @cybernetex/kbn-i18n 支持 TypeScript 吗？

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

### @cybernetex/kbn-i18n 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cybernetex/kbn-i18n 可以商用吗？

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

### @cybernetex/kbn-i18n 的下载量有多少？

根据 npm 官方下载统计，@cybernetex/kbn-i18n 在 2026/10/11 – 2026/11/09 这 30 天内被下载 7,248 次，日均约 242 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cybernetex/kbn-i18n 还在维护吗？

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