# @kne/react-intl

> 快捷地创建国际化中需要使用到的组件

Latest version **0.1.15** (published 2026-07-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install @kne/react-intl
pnpm add @kne/react-intl
yarn add @kne/react-intl
bun add @kne/react-intl
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.15 |
| Published | 2026-07-24 |
| First published | 2025-01-20 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 80.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | linzp |
| Maintainers | lingtong, yangwang123456, juliewang, metacoo |

## Links

- npm: https://www.npmjs.com/package/@kne/react-intl
- Repository: https://github.com/kne-union/react-intl
- Issues: https://github.com/kne-union/react-intl/issues
- npm.io page: https://npm.io/package/@kne/react-intl

## Dependencies (3)

- [react-intl](https://npm.io/package/react-intl.md) ^6.8.9
- [@kne/react-fetch](https://npm.io/package/@kne/react-fetch.md) >=1
- [@kne/global-context](https://npm.io/package/@kne/global-context.md) >=1

## Recent versions

- 0.1.15 (latest) — 2026-07-24
- 0.1.12 — 2026-01-12
- 0.1.11-alpha.0 — 2026-01-09
- 0.1.10 — 2025-12-31
- 0.1.9 — 2025-06-17
- 0.1.8 — 2025-06-17
- 0.1.6 — 2025-02-19
- 0.1.5 — 2025-02-18
- 0.1.4 — 2025-02-18
- 0.1.3 — 2025-01-20
- 0.1.2 — 2025-01-20
- 0.1.1 — 2025-01-20
- 0.1.0 — 2025-01-20

## README

# react-intl


### 描述

快捷地创建国际化中需要使用到的组件


### 安装

```shell
npm i --save @kne/react-intl
```


### 概述

这是一个基于 react-intl 的 React 国际化组件库，提供便捷的国际化解决方案。通过封装 Provider 和工具函数，简化了多语言应用的开发流程，支持灵活的命名空间管理和动态语言切换。

核心特性包括：开箱即用的国际化 Provider 工厂函数、支持命名空间的消息隔离、自动加载和管理翻译消息、与全局上下文集成实现自动语言检测、完整的 TypeScript 类型定义支持。组件库兼容 react-intl 的所有功能，同时提供了更简洁的 API 设计。

适用于需要快速实现国际化功能的 React 应用，特别适合中大型项目的多语言支持，包括电商网站、SaaS 平台、企业后台管理系统等场景。支持组件级和全局级的语言配置，可以根据不同模块独立管理翻译内容。

技术亮点在于提供了多种创建方式，createIntlProvider 用于创建完整的国际化上下文，createWithIntlProvider 可以为单个组件注入国际化能力，createIntl 则适用于非组件环境的国际化场景。消息加载器支持单个和批量加载，命名空间机制确保不同模块的翻译内容互不干扰。

***远程加载语言包***

远程加载语言包功能支持通过 API 动态获取翻译内容，当本地缺少某语言的翻译时自动触发远程请求。提供智能缓存机制，避免重复请求相同的语言包，适用于按需加载、动态扩展语言支持、分包优化等场景。开发者可通过配置全局上下文的 localeMessage 接口，灵活集成后端翻译服务，实现运营人员动态管理翻译内容，无需重新部署应用。

### 示例


#### 示例样式

```scss
.ant-card {
  border-color: black;
  text-align: center;
  width: 200px;
}
```

#### 示例代码

- 基础语言切换
- 实现中英文切换功能，通过下拉选择器实时更新页面语言
- _ReactIntl(@kne/current-lib_react-intl)[import * as _ReactIntl from "@kne/react-intl"],antd(antd)

```jsx
const { createIntlProvider, FormattedMessage } = _ReactIntl;
const { Select, Flex } = antd;
const { useState } = React;

const IntlProvider = createIntlProvider({
  defaultLocale: 'zh-CN',
  messages: {
    'zh-CN': {
      hello: '你好，世界！'
    },
    'en-US': {
      hello: 'Hello, world!'
    }
  }
});

const BaseExample = () => {
  const [locale, setLocale] = useState('zh-CN');
  return (
    <IntlProvider locale={locale}>
      <Flex gap={10}>
        <Select
          placeholder="请选择语言"
          value={locale}
          onChange={setLocale}
          options={[
            { value: 'zh-CN', label: '中文' },
            { value: 'en-US', label: 'English' }
          ]}
        />
        <FormattedMessage id="hello" />
      </Flex>
    </IntlProvider>
  );
};

render(<BaseExample />);

```

- 远程加载语言
- 支持API远程动态加载语言包，扩展多语言支持至日语和德语
- _ReactIntl(@kne/current-lib_react-intl)[import * as _ReactIntl from "@kne/react-intl"],antd(antd),remoteLoader(@kne/remote-loader)

```jsx
const { createIntlProvider, FormattedMessage } = _ReactIntl;
const { Select, Flex } = antd;
const { useState } = React;
const { createWithRemoteLoader } = remoteLoader;

const IntlProvider = createIntlProvider({
  defaultLocale: 'zh-CN',
  namespace: 'test',
  messages: {
    'zh-CN': {
      hello: '你好，世界！',
      remove: '删除'
    },
    'en-US': {
      hello: 'Hello, world!',
      remove: 'remove'
    }
  }
});

const BaseExample = createWithRemoteLoader({
  modules: ['components-core:Global@PureGlobal']
})(({ remoteModules }) => {
  const [PureGlobal] = remoteModules;
  const [locale, setLocale] = useState('zh-CN');
  return (
    <PureGlobal
      preset={{
        apis: {
          localeMessage: {
            // local-first（默认）：本地无当前语言包时才请求
            // remote-first：始终请求远程，远程覆盖本地同名字段
            // off：不请求远程
            // url 模式响应须为扁平 { [id]: text }，例如：
            // url: '/api/v1/intl-admin/lang-lib/messages',
            // method: 'GET',
            strategy: 'local-first',
            loader: ({ data }) => {
              console.log('params', data);
              const lang = {
                'ja-JP': {
                  hello: 'こんにちは、世界！'
                },
                'de-DE': {
                  hello: 'Hallo, Welt!'
                }
              };

              return Promise.resolve(lang[data.locale]);
            }
          }
        }
      }}
    >
      <IntlProvider locale={locale}>
        <Flex gap={10}>
          <Select
            placeholder="请选择语言"
            value={locale}
            onChange={setLocale}
            options={[
              { value: 'zh-CN', label: '中文' },
              { value: 'en-US', label: 'English' },
              { value: 'ja-JP', label: '日本語' },
              { value: 'de-DE', label: 'Deutsch' }
            ]}
          />
          <FormattedMessage id="hello" />
        </Flex>
      </IntlProvider>
    </PureGlobal>
  );
});

render(<BaseExample />);

```

- 多层级显示
- 父子组件嵌套使用不同语言包，子组件可共享父组件国际化资源
- _ReactIntl(@kne/current-lib_react-intl)[import * as _ReactIntl from "@kne/react-intl"],antd(antd)

```jsx
const { createIntlProvider, FormattedMessage, createWithIntlProvider } = _ReactIntl;
const { Select, Flex } = antd;
const { useState } = React;

const IntlProvider = createIntlProvider({
  defaultLocale: 'zh-CN',
  messages: {
    'zh-CN': {
      hello: '你好，世界！'
    },
    'en-US': {
      hello: 'Hello, world!'
    }
  }
});

const ChildrenComponent = createWithIntlProvider({
  defaultLocale: 'zh-CN',
  messages: {
    'zh-CN': {
      childrenMessage: '我是子组件显示信息'
    },
    'en-US': {
      childrenMessage: 'I am the child component displaying information.'
    }
  }
})(() => {
  return (
    <>
      <FormattedMessage id="childrenMessage" />&<FormattedMessage id="hello" />
    </>
  );
});

const BaseExample = () => {
  const [locale, setLocale] = useState('zh-CN');
  return (
    <IntlProvider locale={locale}>
      <Flex gap={10}>
        <Select
          placeholder="请选择语言"
          value={locale}
          onChange={setLocale}
          options={[
            { value: 'zh-CN', label: '中文' },
            { value: 'en-US', label: 'English' }
          ]}
        />
        <FormattedMessage id="hello" />
        <div>----------------</div>
        <ChildrenComponent />
      </Flex>
    </IntlProvider>
  );
};

render(<BaseExample />);

```


### API

### createIntlProvider
创建国际化 Provider 组件，为子组件提供 i18n 上下文。支持配置默认语言、翻译消息和命名空间，返回的 Provider 组件可以动态切换语言。

#### 配置参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| args | string \| object \| array | 是 | - | 支持三种格式：(1) 字符串：默认语言标识 (2) 对象：包含 defaultLocale、defaultMessage、namespace、messages (3) 数组：[defaultLocale, defaultMessage, namespace] |

#### Provider 属性
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 否 | zh-CN | 当前语言标识，优先级高于默认值 |
| children | ReactNode \| function | 是 | - | 子组件或渲染函数，函数形式接收 intl 对象 |

### createWithIntlProvider
创建高阶组件，为被包装组件添加国际化能力。返回的 HOC 函数接受组件并返回带有国际化上下文的组件。

#### 配置参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| args | string \| object \| array | 是 | - | 支持三种格式：(1) 字符串：默认语言标识 (2) 对象：包含 defaultLocale、defaultMessage、namespace、messages (3) 数组：[defaultLocale, defaultMessage, namespace] |

#### HOC 返回组件属性
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 否 | zh-CN | 当前语言标识，优先级高于默认值 |

### createIntl
创建国际化实例，用于在非组件环境中使用 i18n 功能，例如在工具函数、API 调用等场景。

#### 配置参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 否 | zh-CN | 语言标识 |
| message | object | 否 | - | 翻译消息对象 |
| namespace | string | 否 | global | 命名空间 |

#### 返回值
| 类型 | 说明 |
|------|------|
| IntlShape | react-intl 的国际化实例对象 |

### localeLoader
加载指定语言的翻译消息到指定命名空间。

#### 方法参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 是 | - | 语言标识，如 zh-CN、en-US |
| defaultMessage | object | 是 | - | 翻译消息对象，key 为消息 ID |
| namespace | string | 否 | global | 命名空间，用于隔离不同模块的翻译 |

#### 返回值
| 类型 | 说明 |
|------|------|
| object | 更新后的消息对象 |

### messagesLoader
批量加载多语言消息对象，支持同时加载多种语言的翻译内容。

#### 方法参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| messages | object | 是 | - | 多语言消息对象，key 为语言标识，value 为该语言的翻译消息 |
| namespace | string | 否 | global | 命名空间，用于隔离不同模块的翻译 |

### message
存储所有已加载的翻译消息的容器对象，结构为多层嵌套对象，按语言和命名空间组织。

#### 数据结构
| 层级 | 类型 | 说明 |
|------|------|------|
| 第一层 key | string | 语言标识，如 zh-CN、en-US |
| 第二层 key | string | 命名空间，如 global、user |
| 第三层 | object | 翻译消息键值对 |

### IntlProvider
react-intl 的国际化 Provider 组件，提供完整的国际化上下文支持。

#### 属性说明
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 是 | - | 当前语言 |
| messages | object | 是 | - | 翻译消息对象 |
| children | ReactNode | 是 | - | 子组件 |

### apis.localeMessage（preset 远程语言包）
通过全局 `preset.apis.localeMessage` 配置远程语言包接口（`@kne/react-fetch` 配置），并可用 `strategy` 控制加载策略。

```js
preset={{
  apis: {
    localeMessage: {
      url: '/api/...', // 或 loader
      strategy: 'local-first' // 'remote-first' | 'local-first' | 'off'
    }
  }
}}
```

| strategy | 说明 |
|----------|------|
| `remote-first` | 配置了接口则始终请求远程；与本地合并，远程覆盖同名字段；远程空则回退本地 |
| `local-first` | **默认**。仅当前语言本地无包、且存在默认语言包时请求远程 |
| `off` | 永不请求远程（即便配置了接口） |

未配置 `apis.localeMessage` 时不发起远程请求。未写 `strategy` 时按 `local-first` 处理。

**响应格式（必读）**：接口经 `@kne/react-fetch` 的 `transformResponse` 后，`render` 收到的 `data`（即 `results`）必须是扁平文案对象：

```js
{ "Hello": "你好", "Save": "保存" }
```

不要返回 `pageData`、`.i18n` 文件内容等结构。请求时会自动带上 query/body：`locale`、`namespace`（当前 withLocale 命名空间，缺省 `global`）。

推荐后端接口：`GET /api/v1/intl-admin/lang-lib/messages?locale=zh-CN&namespace=global`。

### 默认导出
默认导出为 createIntl 函数，用于创建国际化实例。

#### 配置参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| locale | string | 否 | zh-CN | 语言标识 |
| message | object | 否 | - | 翻译消息对象 |
| namespace | string | 否 | global | 命名空间 |

#### 返回值
| 类型 | 说明 |
|------|------|
| IntlShape | react-intl 的国际化实例对象 |

---
_Source: https://npm.io/package/@kne/react-intl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._