1. 简繁转换原理分析
前面已经介绍过 quick-chinese-transfer 的基本使用姿势,支持简体、繁体、香港繁体、台湾繁体之间的相互转换。这篇教程来聊一聊它的核心实现原理:一个 java 库,是怎么做到不依赖分词器、不依赖 NLP 工具,还能把"软件"转成台湾的"軟體",把"里面的里"转成"裡面"的?
项目地址:https://github.com/liuyueyi/quick-chinese-transfer 对应模块:
transfer-core(maven 坐标com.github.liuyueyi:quick-transfer-core,当前最新版本0.2.18)
1. 为什么简繁转换没那么简单
如果只是"简体字 ↔ 繁体字"一一对应,那一张字符映射表就够了。但实际场景中有三个坑:
坑一:一字对多字
简体的"里",对应繁体可能是"裡"(里面 → 裡面),也可能是"里"(公里 → 公里);简体的"面",繁体可能是"麵"(面条),也可能是"面"(面孔 → 面孔)。单纯按字替换必然出错。
坑二:地区用词差异
同一个东西,大陆叫"软件",台湾叫"軟體";大陆叫"数据库",台湾叫"資料庫"。这种词汇级别的差异,单字映射表根本覆盖不了。
坑三:一词对一字
反过来繁转简时,繁体的多个字/词可能都对应简体的同一个字,需要词组级别的上下文来判断(比如"頭髮"转"头发",而不是"头發")。
所以简繁转换的本质是:单字映射 + 词组(最长匹配)映射 + 地区词典 三层结构,配合贪心最长前缀匹配算法。这也是下文整个设计的出发点。
2. 整体架构
先上全景图,transfer-core 的类不多,一眼就能看明白:
com.github.liuyueyi.quick.transfer
├── ChineseUtils.java // 对外统一入口(静态门面)
├── Trie.java / TrieNode.java // 字典树,负责词组的最长前缀匹配
├── constants/TransType.java // 8 种转换类型枚举
└── dictionary
├── DictionaryContainer.java // 单例容器 + 词典缓存
├── DictionaryFactory.java // 从 classpath 加载 .txt 词典并解析
├── BasicDictionary.java // 单向词典:charMap(单字) + Trie(词组),核心 convert 逻辑
└── SecondParserDictionary.java // 链式词典:两段词典串联(实现 s2hk/tw2s 等)
调用链路只有一条主线:
ChineseUtils.s2t(text)
└──> DictionaryContainer.getInstance().getDictionary(SIMPLE_TO_TRADITIONAL) // 懒加载 + 缓存
└──> BasicDictionary.convert(text) // 真正干活的地方
所有公开 API(s2t、t2s、s2hk、hk2s、s2tw、s2twp、tw2s、transfer...)内部都是一行委托:
public static String s2t(String content) {
return DictionaryContainer.getInstance()
.getDictionary(TransType.SIMPLE_TO_TRADITIONAL)
.convert(content);
}
3. 词典:一切转换的根基
3.1 词典文件
词典全部打包在 jar 内,位于 transfer-core/src/main/resources/tc/ 目录,一共 5 个纯文本文件:
| 文件 | 方向 | 规模 | 说明 |
|---|---|---|---|
s2t.txt | 简 → 繁 | 52826 行 | 通用简繁词典(词组 + 单字),源自 HanLP 的 tc 词典 |
t2s.txt | 繁 → 简 | 9974 行 | 通用繁简词典 |
t2tw.txt | 繁 → 台湾正体 | 509 行 | 台湾字形差异、异体字(裏=裡、麪=麵...)+ 少量 IT 词汇(軟件=軟體、打印机=印表機...) |
t2twp.txt | 繁 → 台湾常用语 | 507 行 | 台湾常用词汇(軟件=軟體、並行計算=平行計算...),源自 OpenCC |
t2hk.txt | 繁 → 香港繁体 | 87 行 | 香港地区异体字标准化(僞=偽、癡=痴...)+ 香港地名"涌"字特殊处理 |
为什么只有 5 个文件却能支持 8 种转换方向?关键在两个设计:同一个文件可以正着读也可以反着读(
hk2s就是把t2hk.txt的 key/value 互换后加载),以及链式转换(s2hk= 先s2t再t2hk),后面第 5 节细说。
3.2 词典格式
每行一条 key=value 映射,# 开头为注释行,空行跳过:
# t2tw.txt 片段
软件=軟體
数据库=資料庫
打印机=印表機
裏=裡
3.3 解析过程(DictionaryFactory)
DictionaryFactory.loadDictionary(mappingFile, reverse) 做的事情:
- 以 UTF-8 从 classpath 读取词典文件;
- 逐行解析:手动找到第一个
=的下标然后substring切分,而不是String.split——避免正则的开销和转义问题,这种小细节在词典有几万行时很有效果; - 分流存储:
key.length() == 1 && value.length() == 1→ 放入charMap: Map<Character, Character>(单字映射表,O(1) 查找)- 否则 → 放入
Trie<String>(词组字典树,最长前缀匹配)
- 每加入一个多字词组,同步更新
maxLen(最长词组长度),它是后面 PushbackReader 回退缓冲区大小的依据; reverse = true时,key/value 在加载阶段就互换——tw2s复用t2tw.txt靠的就是这个参数。
注意:文件方向是加载时就定死的,而不是转换时才判断。同一个
t2hk.txt,s2hk用它读作「简/异体 → 香港标准」,hk2s用它(reverse=true)读作「香港标准 → 繁体」。
3.4 缓存与懒加载(DictionaryContainer)
DictionaryContainer 是经典的双重检查锁单例(volatile + synchronized),内部用一个 Map<String, BasicDictionary> 做词典缓存,key 是转换类型的字符串("s2t"、"t2s"...)。
getDictionary(TransType) 的逻辑:
查缓存 → 命中直接返回
→ 未命中:synchronized 双检 → 按类型构建词典 → 放入缓存
构建规则是一个 switch,8 种类型分成两类:
| TransType | 构建方式 |
|---|---|
s2t / t2s | 直接 loadDictionary("tc/xxx.txt"),单段词典 |
s2hk / s2tw / s2twp | loadSecondDictionary(s2t字典, "tc/t2xx.txt"),链式词典 |
hk2s / tw2s / tw2sp | loadSecondDictionary(t2s字典, "tc/t2xx.txt", reverse=true),链式词典 |
懒加载的好处是按需加载、不浪费内存:如果你只用 s2t,那就只有一份 s2t 词典驻留内存。代价是首次调用会有一次加载 5 万+ 行词典的开销(毫秒级),所以对性能敏感的场景建议先预热(见第 7 节)。
4. 核心:Trie 最长前缀匹配
4.1 Trie 结构
Trie<T> 是一个标准的泛型字典树:
TrieNode节点包含:children(HashMap)、leaf(是否是完整词)、value(词对应的转换结果)、level(节点在树中的深度 = 匹配到这个节点消耗的字符数);add(String, T):逐字符下钻建树,末节点置leaf=true存 value;bestMatch(char[] buf, offset, len):贪心走到底。
4.2 贪心最长匹配的关键
bestMatch 的实现思路值得单独说:从根出发,从 offset 开始逐字符下探,每遇到一个叶子节点就把它记为"当前最优结果"(不断覆盖),直到某一步的孩子不存在才 break。也就是说:
不是"第一个命中就返回",而是"一路走到底,最后一次叶子命中即最长匹配"。
这个设计直接决定了"排除词"功能的实现方式——比如不希望"国"被转成"國",就把 国=国 作为自映射词组加进 Trie。词组匹配命中 2 字长的"自映射",天然优先于单字 charMap 里的 国→國,"国"就保持原样了。这是个非常取巧的设计,后面第 6 节还会用到它。
4.3 convert 的整体流程(BasicDictionary)
真正干活的 convert,核心流程如下:
// 伪代码,还原 BasicDictionary.convert 的逻辑
PushbackReader reader = new PushbackReader(input, maxLen); // 回退缓冲 = 最长词组长度
while ((c = reader.read()) != -1) {
reader.mark(maxLen);
读 maxLen 个字符到 buf;
TrieNode node = trie.bestMatch(buf, 0, maxLen);
if (node != null) {
// 词组命中:写出词组的 value,把未消费的字符回退 unread
output.write(node.value);
reader.unread(剩余字符);
} else {
// 词组未命中:回退到单字映射,字典里没有的字符原样透传
reader.reset();
output.write(charMap.getOrDefault(c, c));
}
}
三个性能要点:
- 单字走 charMap(O(1) HashMap),词组走 Trie(O(maxLen) 下探),两层结构按命中率分层处理;
- PushbackReader 的回退缓冲区大小恰好等于 maxLen,既保证最长词组能完整试探,又避免了对 String 反复
substring的开销; - 词典里没有的字符原样透传,所以英文、数字、emoji 混在中文里转都没问题。
匹配复杂度:每个字符 O(maxLen) 的 Trie 下探 + O(1) 的单字兜底,maxLen 通常很小(词典里最长词组也就几个字),所以海量短文本转换的吞吐非常高。整个库不依赖任何分词器,纯贪心最长匹配,这也是它"快"的原因。
5. 链式转换(SecondParserDictionary)
SecondParserDictionary 是一个包装器,持有两个词典:parent(第一段)和 dictionary(第二段),convert 就是把两段串联起来:
reverse = false(s2hk/s2tw/s2twp):先 parent 后 dictionary,即先通用简→繁,再做地区词汇/字形转换;reverse = true(hk2s/tw2s/tw2sp):先 dictionary 后 parent,即先做地区归一,再繁→简。
以 s2hk 为例,"说"字的旅程是:
说 --s2t.txt: 说→說--> 說 --t2hk.txt: 說→説--> 説(香港标准)
再看 s2tw 与 s2twp 的区别(0.2.18 新增了 s2twp):
// s2tw:台湾字形 + 基础 IT 词汇(对应 OpenCC 的 s2tw)
ChineseUtils.s2tw("视频数据"); // 視訊資料
// s2twp:台湾字形 + 完整台湾常用语词典(对应 OpenCC 的 s2twp)
ChineseUtils.s2twp("视频数据"); // 影片資料
两者共用同一段 s2t 基础词典,区别只在第二段挂的是 t2tw.txt(509 行,台湾字形 + 基础 IT 词汇)还是 t2twp.txt(507 行,源自 OpenCC 的台湾常用语全集)。这就是"基础版"与"增强版"两层地区词典的组合玩法。
顺带一提 t2hk.txt 里一个有意思的细节:香港地名里的"涌"(如葵涌、鰂魚涌)不应该被转成"湧",词典里用多行 X涌=X涌 的自映射来保护——又是第 4.2 节说的那个机制。
6. 自定义词典与排除词(0.2.16+)
词典再多也覆盖不了所有业务场景,所以 0.2.16 提供了两个口子:
6.1 加自定义转换词典
Map<String, String> map = new HashMap<>();
map.put("发展国家", "發达國家");
ChineseUtils.loadAdditionalDict(TransType.SIMPLE_TO_TRADITIONAL, map);
底层就是调 BasicDictionary.add(key, value):单字进 charMap,多字进 Trie,和内置词典一视同仁。
6.2 加排除词(不参与转换)
// 简转繁时,"国" 和 "发展国家" 保持原样
ChineseUtils.loadExcludeDict(TransType.SIMPLE_TO_TRADITIONAL, Arrays.asList("发展国家", "国"));
// 也可以全局生效:所有转换类型都保持原样
ChineseUtils.loadExcludeDict(Arrays.asList("发展国家", "国"));
它的实现就是第 4.2 节说的自映射:把排除词按 word=word 加进 Trie,贪心最长匹配会让它赢过单字替换。对已加载的词典则执行 remove(word)(Trie 节点的 value 摘除)。
另外 loadExcludeDict 会把排除词记录在容器的 selfExcludeWords 里,unLoad 后重新加载词典时会自动重放,排除设置不会丢。
6.3 两个使用上的坑
- unLoad 后再 loadAdditionalDict 会丢自定义词:自定义词是加在"当时的词典实例"上的,unLoad 移除缓存后重建词典不会重放它们(排除词有持久化记录所以不受影响)。建议把加词放在启动初始化阶段一次性做完;
- 动态加词与并发转换有竞态:
loadAdditionalDict直接写正在使用的 HashMap/Trie 且无锁,官方姿势都是"先 preLoad、再加词、再提供服务",不要在转换高峰期动态加词。
7. 预加载与卸载
// 同步预热:阻塞直到词典加载完成
ChineseUtils.preLoad(TransType.SIMPLE_TO_TRADITIONAL);
// 异步预热:起守护线程后台加载,不阻塞主流程
ChineseUtils.preLoad(true, TransType.values());
// 卸载:内存敏感时释放无用词典
ChineseUtils.unLoad(TransType.SIMPLE_TO_TRADITIONAL, TransType.TRADITIONAL_TO_SIMPLE);
异步预加载的实现很朴素:new 一个 daemon 线程,线程内对每个 type 调用一次 transfer("", type)——空串转换会触发 getDictionary,从而强制构建缓存。所谓"预热"其实就是把懒加载提前触发一次。守护线程的另一个好处是不阻止 JVM 退出。
线程安全性总结:
- convert 是只读操作,词典加载完成后天然线程安全,可以放心并发调用;
- 词典懒构建有双检锁,并发首次调用同一类型只会构建一次;
- 需要注意的只有 6.3 说的动态加词竞态。
8. 小结
把整个库的原理压缩成三句话:
- 词典层:5 个
key=value文本词典,单字进 HashMap、词组进 Trie,一个文件正反两读; - 算法层:贪心最长前缀匹配 + PushbackReader 回退 + 单字 O(1) 兜底,不依赖分词器;
- 组合层:链式词典把"通用简繁"与"地区差异"两个正交问题拆开,8 种转换方向全部由 5 份词典组合而来。
理解了这三个设计,再去读源码(transfer-core 全部核心代码不到 1000 行)会非常轻松。下一篇教程我们来看同仓库的另一个模块 hanzi-writer,它是怎么把一个汉字拆成一笔一画并渲染成 SVG 动画的。
相关链接
- 项目地址:https://github.com/liuyueyi/quick-chinese-transfer
- 参考项目:
- HanLP 的 tc 简繁词典
- luhuiguo/chinese-utils(Trie/BasicDictionary 骨架的出处)
- OpenCC(台湾/香港词汇词典的出处)
- 在线体验:查笔顺 APP 在线版