# @halofe/global-string-format 中文文档

规范地址：https://npmcn.com/package/%40halofe/global-string-format/

版本：1\.0\.8
npm 元数据更新时间：2022-04-05T16:45:29.285Z
中文译文更新时间：2026-11-17T06:54:17.968Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40halofe/global-string-format
原文对照：https://npmcn.com/package/%40halofe/global-string-format/?lang=original

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

- 包体积（解压后）：42.8 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2022-02-16T07:32:24.524Z
- 最新版本发布：2022-02-16T08:04:45.443Z
- 近 30 天下载量：7817（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

@halofe/global-string-format 提供普通文案国际化能力，业务方传入数据字典，组件返回 id 对应的文案。

## 安装

```sh
npm install @halofe/global-string-format
```

也可以使用：`pnpm add @halofe/global-string-format`、`yarn add @halofe/global-string-format`、`bun add @halofe/global-string-format`

## README

## @halofe/global-string-format

@halofe/global-string-format 提供普通文案国际化能力，业务方传入数据字典，组件返回 id 对应的文案。

### 主要特征

-   提供获取普通文案的国际化能力
-   可以在浏览器和 node 环境中运行
-   基于国际化[多语言标准](https://yuque.antfin/#inc.com/ioc-1/specification/bvyc20)
-   支持 react/rax 对象作为变量
-   同时支持 index 和 name 作为变量索引
-   结合使用 [babel-plugin-string-format](http://gitlab.alibaba/#inc.com/parrot/babel-plugin-string-format) 可以解决依赖组件的文案收集和透传的问题

### 安装

```
tnpm install @halofe/global-string-format --save
```

### 使用

#### 基本使用

```js
// src/index.js

import stringFormat from "@halofe/global-string-format";

// 初始化一个实例,并将这个实例挂载到全局变量(window/global)上. 在一些通用组件可以直接用这个实例进行格式化.
stringFormat.init("en-US", {
  "en-US": {
    no_variable: "I have noe messages",
    variable_test_for_index: "I have {0} messages",
    variable_test_for_name: "I have {count} messages",
  },
  "zh-CN": {
    no_variable: "我没有消息",
    variable_test_for_index: "我有 {0} 条消息",
    variable_test_for_name: "我有 {count} 条消息",
  },
});

// 输出多语言
stringFormat.format({
  id: "no_variable",
  defaultString: "I have noe messages",
});
// 输出
// I have noe messages

// 使用 index  作为变量的索引
stringFormat.format(
  {
    id: "variable_test_for_index",
    defaultString: "I have {0} messages",
  },
  [2]
);

// 输出
// I have 2 messages

// 使用 name 作为变量的缩影
stringFormat.format(
  {
    id: "variable_test_for_name",
    defaultString: "I have {count} messages",
  },
  { count: 1 }
);

// 输出
// I have 2 messages
```

在其他的页面或者依赖组件中, 直接调用 `stringFormat.Format` , 使用首次初始化的实例进行格式化.

```js
// src/component/other/index.js
import stringFormat from "@halofe/global-string-format";
// 使用全局共享的实例进行多语言格式化
stringFormat.format({
  id: "no_variable",
  defaultString: "I have noe messages",
});
// 输出
// I have noe messages
```

#### React Dom 作为变量

```js
import  from 'react';
import  stringFormat from '@halofe/global-string-format';
const messageCountSpan = (<span style={{color: 'red'}}>2</span>);
stringFormat.format({
  id: 'variable_test_for_index',
  defaultString: 'I have {0} messages'
},[messageCountSpan],{
  React // 注意: 需要将 React 作为参数传入
})
```

### 其他的 API

#### 使用 StringFormat 对象

1.StringFormat：使用 StringFormat 实例化。 2.format：使用 StringFormat 实例的 format 方法，返回每条 id 对应的文案。

```js
import sf from "@halofe/global-string-format";
/**
 *  @param locale Languages that need to be localized
 *  @param strings Data dictionary, ICU grammar
 */
const stringFormat = new sf.StringFormat("zh-CN", {
  "en-US": {
    hello_world: "hello world",
  },
  "zh-CN": {
    hello_world: "你好，国际化",
  },
});

// 获取传入的 strings
stringFormat.getStrings();

// 进行格式化
stringFormat.format({
  id: "hello_world",
  defaultString: "hello world",
});
```

## 常见问题

### @halofe/global-string-format 是什么？

@halofe/global-string-format 提供普通文案国际化能力，业务方传入数据字典，组件返回 id 对应的文案。

### 如何安装 @halofe/global-string-format？

在项目目录运行 npm install @halofe/global-string-format，或使用 pnpm add / yarn add / bun add。

### @halofe/global-string-format 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/halofe\_\_global-string-format 是否存在。

### @halofe/global-string-format 支持 ESM 还是 CommonJS？

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

### @halofe/global-string-format 可以商用吗？

@halofe/global-string-format 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @halofe/global-string-format 的下载量有多少？

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

### @halofe/global-string-format 还在维护吗？

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

