# @dawn-studio/zh-convert 中文文档

规范地址：https://npmcn.com/package/%40dawn-studio/zh-convert/

版本：0\.5\.0
npm 元数据更新时间：2026-10-24T10:40:04.110Z
中文译文更新时间：2026-11-14T07:52:28.756Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dawn-studio/zh-convert
原文对照：https://npmcn.com/package/%40dawn-studio/zh-convert/?lang=original
项目主页：https://github.com/hectorchanht/dawn-zh-convert#readme
源码仓库：https://github.com/hectorchanht/dawn-zh-convert

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

- 包体积（解压后）：93.6 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-10-23T07:34:25.545Z
- 最新版本发布：2026-10-24T10:40:03.915Z
- 近 30 天下载量：2118（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Dawn Studio应用的中文脚本转换:简化了"-"传统(口语-意识,一相机),懒得装入,永远不扔出. 引擎:tungwen-core + tongwen-ditt(MIT,默认)和OpenCC通过opencc-js(opt-in,以配置为主: s2t/s2tw/s2hk/s2twp/t2s/

## 安装

```sh
npm install @dawn-studio/zh-convert
```

也可以使用：`pnpm add @dawn-studio/zh-convert`、`yarn add @dawn-studio/zh-convert`、`bun add @dawn-studio/zh-convert`

## README

# @dawn-studio/zh-convert (中文(简体) )

Dawn Studio应用的中文脚本转换: **简化 传统** (口口口口口口口口口口口口口口口口口口口口口口口口口口相口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口口 取自 OpenMusic 的战斗测试 `zh-convert` + 键 `i18n/detect` 模块.

默认引擎 : [`tongwen-core`](https://www.npmjs.com/package/tongwen-core) + 键 [`tongwen-dict`](https://www.npmjs.com/package/tongwen-dict) (两者都是麻省理工学院)——被宣布为真正的依赖,自动安装. 自0.5.0起,还有一个 **选入 OpenCC 引擎** (基于配置,见下文). 此套件添加了房屋层 :

-   **懒惰,被纪念的口袋** 通过动态 `import()` —— ~72 KB s2t /~22 KB t2s表不要在初始捆绑中,最多一次取出.
-   **同步手柄** (单位:千美元)`s2tConvertLineSync`, (中文(简体) ), `t2sConvertLineSync`),一经发热就发表——"不发"先出.
-   **同上文 s2t 合并** ——tongwen's s2t sparating table 在简化上键入,所以一个已经-传统-QQ的 s2t 直接错过了短语和per-char地图 → → (~). 合并后折叠为先被简化后,再由每个代码点在t2s改变字符的地方保留出源拼写.
-   **永不掷出** 任何进口/建造/转换失败都会降解为身份,从不丢弃.
-   **日本警卫** ——kana/hangul-first分类符指日语行(kana sent)从未被错误地传统化.

## 安装

```bash
npm i @dawn-studio/zh-convert
```

## 快开始

```ts
import {
  lockScriptSync,   // force one line into a script — the entry point most apps want
  warmScript,       // await dict builds so the first render doesn't flash
  s2tConvertLines,  // batch Simplified → Traditional (position-aligned)
  t2sConvertLines,  // batch Traditional → Simplified
  isChineseLine,    // predicate: safe to convert offline?
  detectLang,       // pure classifier: en | zh-Hant | zh-Hans | ja | ko
  shouldTranslate,  // per-text-unit "should this be translated?" decision
} from '@dawn-studio/zh-convert';

// 1. Warm early (e.g. app boot) when the target is Traditional:
await warmScript('zh-Hant');

// 2. Force any upstream text into the user's script — Chinese only, everything
//    else passes through untouched, never throws, never returns null:
lockScriptSync('周杰伦', 'zh-Hant'); // → '周杰倫'
lockScriptSync('周杰倫', 'zh-Hant'); // → '周杰倫' (idempotent — source spelling kept)
lockScriptSync('こんにちは', 'zh-Hant'); // → 'こんにちは' (Japanese untouched)
```

批量转换( 语言, 搜索结果) :

```ts
await s2tConvertLines(['头发', '', '简体中文']); // → ['頭髮', '', '簡體中文']
await t2sConvertLines(['止戰之殤']);              // → ['止战之殇']
```

渲染回路的不闪烁同步路径——返回 `null` 直到温暖:

```ts
import { warmS2T, s2tConvertLineSync } from '@dawn-studio/zh-convert';
warmS2T(); // fire-and-forget at boot
// ... in render:
const text = s2tConvertLineSync(name) ?? name;
```

## API 密码

| 导出 | 说明 |
| --- | --- |
| `lockScriptSync(text, target, opts?)` | 强制一行进入 `'zh-Hant'`编号 :`'zh-Hans'`永远不扔,永远不废. **用这个.** |
| `warmScript(target)` | 等待 dict 构建锁定目标需要 。 绝不拒绝. |
| `s2tConvertLines(lines, opts?)` | 批次s2t,位置相接,空白保存. |
| `t2sConvertLines(lines, opts?)` | 批t2s,位置相通. 不对已简化的输入操作 . |
| `s2tConvertLineSync(text)` | 同步 s2t( 密码合并) . `null` 直到温暖。 门打开 `isChineseLine` 先说. |
| `t2sConvertLineSync(text)` | 同步 t2s . `null` 直到温暖. |
| `warmS2T()` 编号 : `warmT2S()` | 火而忘热者. |
| `isChineseLine(text)` | `true` 仅用于检测到的中文——卡纳/汉古尔线返回 `false`。 。 。 . |
| `detectLang(text)` | 纯分类器 − `'en' | 'zh-Hant' | 'zh-Hans' | 'ja' | 'ko'`. Kana/Hangul战胜了汉;模糊的汉字默认为 `'zh-Hant'`。 。 。 . |
| `shouldTranslate(text, target, whitelist)` | 每单位翻译决定;中文目标总是通过转换器的路径(在小字符集上检测不可靠). |
| `convertWithConfig(text, config, opts?)` | **OpenCC 路径.** 基于Async的配置转换(每行警卫+保护). 绝不放弃失败的身份. |
| `convertWithConfigSync(text, config, opts?)` | **OpenCC 路径.** 温暖时同步转换; `null` 在寒冷的时候 没有警卫——门先入. |
| `warmConfig(config)` | **OpenCC 路径.** 等待一个配置的懒惰建筑。 绝不拒绝. |
| `isConfigWarm(config)` | **OpenCC 路径.** 配置的同步控件是否准备好 . |
| `OPENCC_CONFIGS` 编号 : `openccConfig(name)` | **OpenCC 路径.** 预设的配置表 / 查找( 未知名称返回到 `s2t`) (中文(简体) ). |

## OpenCC引擎(0.5.0+)-基于配置的转换

模拟 [打开CC](https://github.com/byvoid/opencc)预设 **配置** 系统——与上游OpenCC和 [在线转换器](https://opencc.js.org/converter?config=s2t) (单位:千美元)`?config=s2t`) (中文(简体) ). 以 [`opencc-js`](https://www.npmjs.com/package/opencc-js) (OpenCC的纯-JavaScript端口;取自OpenCC数据的词典,MIT和Apache-2.0)- **没有** 官员 `opencc` npm 软件包,是本地的加通,不能在浏览器或边缘运行.

```ts
import { convertWithConfig, convertWithConfigSync, warmConfig, OPENCC_CONFIGS } from '@dawn-studio/zh-convert';

await convertWithConfig('鼠标', 's2twp');        // → '滑鼠' (Taiwan phrases)
await convertWithConfig('軟體', 'tw2sp');        // → '软件' (Mainland phrases)
await warmConfig('s2t');                          // warm the sync handle…
convertWithConfigSync('汉字', 's2t');             // → '漢字' (null while cold)
```

或通过 OpenCC 路由已有的 API `ConvertOptions`数字 :

```ts
await s2tConvertLines(['鼠标'], { engine: 'opencc', config: 's2twp' }); // → ['滑鼠']
lockScriptSync('汉字', 'zh-Hant', { engine: 'opencc' }); // sync handle — warmConfig('s2t') first; cold → identity
```

默认引擎保留 `tongwen`; OpenCC 严格选入. OpenCC 路径保留每所房子的保证:懒惰的每个配置加载(动态) `import()`,从来没有在初始捆绑),永不扔出身份回落,同一个中国唯一的后卫,以及 `PROTECTED_WORDS` 保护( 在 OpenCC 路径上, cars 也永远不会变成有区别的; QQ 仍然有效) .

### 配置表(上游 OpenCC 名称 QX opencc- js locales)

粗略的脚本锁等同物 : `zh-Hant` ≈ `s2t`, (中文(简体) ), `zh-Hans` ≈ `t2s` - 区域概况`s2tw`, (中文(简体) ), `s2hk`,.)另外规范了区域变体/句子,而脚本锁是故意不这样做的.

| 配置 | 从 至 | 含义 |
| --- | --- | --- |
| `s2t` | (单位:千美元) | 简化 ~ 传统(开放CC标准) |
| `t2s` | 页:1 | 传统(开放CC标准) → 简化 |
| `s2tw` | (单位:千美元) | 简化-传统(台湾标准) |
| `tw2s` | w-克纳 | 传统(台湾)——简化 |
| `s2hk` | (单位:千克) | 简化 ~ 传统 (香港标准) |
| `hk2s` | (单位:千克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 | 传统(香港) • 简化 |
| `s2twp` | (单位:千美元) | 简化了 ~ 传统 (台湾,有台湾语:鼠标→滑鼠,软件→軟體) |
| `tw2sp` | w-克纳 | 传统(台湾) → 简化(有内地语: ) |
| `t2tw` | 页:1 | 传统(开放CC标准) → 传统(台湾) |
| `tw2t` | 页:1 | 传统(台湾) • 传统(开放CC标准) |
| `t2hk` | 页:1 | 传统(开放CC标准) • 传统(香港) |
| `hk2t` | (单位:千美元) | 传统(香港)-传统(开放CC标准) |
| `s2hkp` | (单位:千美元) | 简化了 ~ 传统 (香港,有香港语短语) |
| `hk2sp` | (单位:千美元) | 传统(香港) → 简化(有内地语;上游:仍在发展) |

## 转换选项——每个旋钮,您的呼叫

`lockScriptSync`, (中文(简体) ), `s2tConvertLines` 财务报告和审定财务报表 `t2sConvertLines` 全部接受可选 `opts: ConvertOptions`。没有硬码显示一个合理的应用程序想要改变:

```ts
import { lockScriptSync, type ConvertOptions } from '@dawn-studio/zh-convert';

// The "Chinese only" rule is just the default guard — replace it freely:
lockScriptSync('こんにちは世界', 'zh-Hant');                                  // → unchanged (default guard)
lockScriptSync('简体', 'zh-Hant', { guard: () => true });                     // → '簡體' (allow all)
lockScriptSync('简体', 'zh-Hant', { guard: (t) => t !== '简体' });            // → '简体' (skip this line)

await s2tConvertLines(['简体', '头发'], { guard: isChineseLine });            // explicit default
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `guard` | `(text: string) => boolean` | `isChineseLine` | 拒绝的行经没有改变。 默认是kana/hangul-first分类器——它已经对混合语言文本做了正确的事情. |
| `protectedWords` | `readonly string[]` | —— 说 | 添加到 `PROTECTED_WORDS`。 。 。 . |
| `engine` | `'tongwen' | 'opencc'` | `'tongwen'` | 转换引擎. `'opencc'` (一) 直接引导合成分批转换器; `lockScriptSync` 使用温暖的 OpenCC 同步手柄( cold ) . |
| `config` | `OpenCCConfigName` | `'s2t'` 编号 : `'t2s'` 每个入境点 | OpenCC 配置名称; 只当 `engine: 'opencc'`。 。 。 . |

## 页:1

-   引擎与归属:通格文词典为MIT(通格文/通格文-ditt;OpenCC词典由OpenCC数据出自Opencc-js(开克-js为MIT和Apache-2.0;OpenCC数据为Apache-2.0). 这个包本身是Apache-2.0.
-   s2t和t2s 命令已经建立 **单独** ——只收发t2s的调用者从不下载s2t的148KB短语表.
-   深度进口 `tongwen-core/esm/*` (不是顶级指数):指数 eval-time 引用 DOM 全球 `NodeFilter` 扔到没有DOM的地方.
-   已知默认后卫的上限:与 **零卡纳** (pure kanji)检测为中文并会被转换. 覆盖 `guard` 如果你的手术需要更严格的检查.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @dawn-studio/zh-convert 是什么？

Dawn Studio应用的中文脚本转换:简化了"-"传统\(口语-意识,一相机\),懒得装入,永远不扔出\. 引擎:tungwen-core \+ tongwen-ditt\(MIT,默认\)和OpenCC通过opencc-js\(opt-in,以配置为主: s2t/s2tw/s2hk/s2twp/t2s/

### 如何安装 @dawn-studio/zh-convert？

在项目目录运行 npm install @dawn-studio/zh-convert，或使用 pnpm add / yarn add / bun add。

### @dawn-studio/zh-convert 支持 TypeScript 吗？

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

### @dawn-studio/zh-convert 支持 ESM 还是 CommonJS？

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

### @dawn-studio/zh-convert 可以商用吗？

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

### @dawn-studio/zh-convert 的下载量有多少？

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

### @dawn-studio/zh-convert 还在维护吗？

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