🔤 HanTone — 零依赖 · 离线优先的汉字拼音转换引擎 | 多音字词组级消歧 · 注音符号 · 变调 · 中文排序 | Zero-dependency, offline-first Mandarin Pinyin engine
Repo gitstq/HanTone, read from GitHub 11 min ago. gitstq has not joined Take My Repo.
gitstq/HanTone is a public repo on GitHub by gitstq. 🔤 HanTone — 零依赖 · 离线优先的汉字拼音转换引擎 | 多音字词组级消歧 · 注音符号 · 变调 · 中文排序 | Zero-dependency, offline-first Mandarin Pinyin engine. It declares the MIT license on GitHub. It is written mainly in Python, has 0 stars and last changed on 2026-10-31. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
零依赖 · 离线优先的汉字拼音转换引擎 Zero-dependency, offline-first Mandarin Pinyin conversion engine
🌐 选择语言 / Choose Language:
HanTone 是一个零第三方依赖、完全离线的汉字拼音转换引擎,用纯 Python 标准库实现。
它解决的不是「把汉字查表换成拼音」这种简单问题,而是中文处理中最容易翻车的那件事——多音字。
大多数拼音工具在单字层面工作,于是「银行」被读成
yín xíng、「重庆」被读成zhòng qìng。 HanTone 在词组层面做消歧,因此yín háng和chóng qìng才是它的答案。
| 😖 痛点 | ✨ HanTone 的解法 |
|---|---|
| 「银行 / 行走」读音不分 | 🎯 405 条词组级消歧规则,最长正向匹配 |
| 「重庆 / 重要」地名读错 | 🗺️ 内置地名专用读音(重庆、厦门、六安、丽水……) |
| 姓氏「单 / 仇 / 查」读错 | 👤 mode='surname' 姓氏模式,含 59 条复姓规则 |
| Python 中文排序不符合习惯 | 🔤 sort_key() 按拼音排序,而非 Unicode 码点 |
| 「一 / 不」的变调不会标 | 🗣️ sandhi=True 开启口语变调与三声变调 |
| 需要注音符号教学 | 🎵 内置 ㄅㄆㄇㄈ 注音符号(Bopomofo)输出 |
| 离线环境 / 内网无法装包 | 📦 零依赖,只用一个 .py 包,断网照跑 |
kuài lè 而不是 kuài le。sorted(names, key=hantone.sort_key)slug('汉语拼音') → han-yu-pin-yinheteronym() 列出全部读音,explain() 附带英文释义pinyin / slug / initials / sort / lookup / info 六个子命令zlib / base64 / argparse / unicodedata# 方式一:从源码安装(推荐)
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make install # 等价于 pip install -e .
# 方式二:直接用 PyPI 包
pip install hantone
# 方式三:零安装 —— 把 hantone/ 目录拷进你的项目即可
import hantone
hantone.convert('中国银行') # => 'zhōng guó yín háng'
hantone.convert('重庆') # => 'chóng qìng'
hantone.convert('音乐') # => 'yīn yuè'
python -m hantone pinyin 中国银行
# zhōng guó yín háng
python -m hantone pinyin 好好学习 --sandhi
# háo hǎo xué xí
python -m hantone slug 汉语拼音转换引擎
# han-yu-pin-yin-zhuan-huan-yin-qing
python -m hantone sort 张三 李四 王五 赵六
# 李四 / 王五 / 张三 / 赵六
python -m hantone lookup 行
convert()import hantone
hantone.convert('中华人民共和国')
# 'zhōng huá rén mín gòng hé guó'
hantone.convert('你好,世界!')
# 'nǐ hǎo,shì jiè!' ← 标点两侧自动不加多余空格
hantone.convert('中国 ABC 2026')
# 'zhōng guó ABC 2026' ← 英文与数字保持原样
参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
style |
'mark' |
输出风格,见下表 |
separator |
' ' |
分隔符;非空格时对所有片段统一连接 |
mode |
'normal' |
'surname' 启用姓氏读音 |
sandhi |
False |
True 启用口语变调(默认输出规范本调) |
erhua |
False |
True 合并词尾儿化音 |
errors |
'default' |
'ignore' 丢弃非汉字;'keep' 保留 |
text = '中华人民共和国'
hantone.convert(text, style='mark') # 'zhōng huá rén mín gòng hé guó' 声调符号
hantone.convert(text, style='number') # 'zhong1 hua2 ren2 min2 gong4 he2 guo2'
hantone.convert(text, style='plain') # 'zhong hua ren min gong he guo'
hantone.convert(text, style='initial') # 'zh h r m g h g' 声母
hantone.convert(text, style='first') # 'z h r m g h g' 首字母
hantone.convert(text, style='zhuyin') # 'ㄓㄨㄥ ㄏㄨㄚˊ ㄖㄣˊ ㄇㄧㄣˊ ㄍㄨㄥˋ ㄏㄜˊ ㄍㄨㄛˊ'
hantone.convert('银行') # 'yín háng' ✅ 不是 yín xíng
hantone.convert('行走') # 'xíng zǒu'
hantone.convert('重庆') # 'chóng qìng' ✅ 不是 zhòng qìng
hantone.convert('重要') # 'zhòng yào'
hantone.convert('音乐') # 'yīn yuè'
hantone.convert('快乐') # 'kuài lè' ✅ 轻声规则不会误伤
hantone.convert('厦门') # 'xià mén'
hantone.convert('六安') # 'lù ān'
hantone.convert('出差') # 'chū chāi'
hantone.convert('下载') # 'xià zài'
hantone.convert('单') # 'dān'
hantone.convert('单', mode='surname') # 'shàn' ✅
hantone.convert('仇', mode='surname') # 'qiú'
hantone.convert('查', mode='surname') # 'zhā'
hantone.convert('曾', mode='surname') # 'zēng'
hantone.convert('解', mode='surname') # 'xiè'
hantone.convert('尉迟', mode='surname') # 'yù chí' ✅ 复姓
hantone.convert('万俟', mode='surname') # 'mò qí'
默认输出《汉语拼音方案》规范本调;需要口语实际读音时开启 sandhi=True。
hantone.convert('你好') # 'nǐ hǎo' 规范本调
hantone.convert('你好', sandhi=True) # 'ní hǎo' 三声变调 ✅
hantone.convert('一个') # 'yī gè'
hantone.convert('一个', sandhi=True) # 'yí gè' 「一」在四声前变二声 ✅
hantone.convert('一天', sandhi=True) # 'yì tiān' 「一」在一声前变四声 ✅
hantone.convert('不是') # 'bù shì'
hantone.convert('不是', sandhi=True) # 'bú shì' 「不」在四声前变二声 ✅
hantone.convert('妈妈', sandhi=True) # 'mā ma' 叠词轻声 ✅
⚠️ 注意:词组规则中已显式标注的读音不会被变调改写, 因此
hantone.convert('快乐', sandhi=True)仍然是kuài lè。
# 按拼音排序中文(修正 Unicode 码点排序的不符合直觉)
names = ['张三', '李四', '王五', '赵六']
sorted(names, key=hantone.sort_key)
# ['李四', '王五', '张三', '赵六']
# 生成 URL 友好别名
hantone.slug('汉语拼音转换引擎') # 'han-yu-pin-yin-zhuan-huan-yin-qing'
hantone.slug('汉语拼音', separator='_') # 'han_yu_pin_yin'
hantone.slug('汉语拼音', tone=True) # 'han4-yu3-pin1-yin1'
# 首字母缩写
hantone.initials('中国银行') # 'zgyh'
hantone.initials('中国银行', style='initial') # 'zhgyh' 完整声母
hantone.heteronym('行') # [['xíng', 'háng', 'héng']]
hantone.explain('中')
# {'char': '中', 'code_point': 'U+4E2D',
# 'pinyin': ['zhōng', 'zhòng'],
# 'zhuyin': ['ㄓㄨㄥ', 'ㄓㄨㄥˋ'],
# 'meaning': 'central; center, middle; in the midst of; hit (target); attain',
# 'heteronym': True}
hantone.hanzi_count() # 44364
hantone.syllable_count() # 1456
python -m hantone pinyin [文本...] [-s STYLE] [-d SEP] [--mode] [--sandhi] [--erhua] [--stdin]
python -m hantone slug [文本...] [-d SEP] [--tone] [--stdin]
python -m hantone initials [文本...] [--full] [--stdin]
python -m hantone sort [条目...] [--no-tone] [--stdin]
python -m hantone lookup 汉字 [-s STYLE]
python -m hantone info
管道用法:
echo 重庆银行 | python -m hantone pinyin --stdin
# chóng qìng yín háng
cat names.txt | python -m hantone sort --stdin
| 🏷️ 场景 | 💻 用法 |
|---|---|
| 博客 URL 生成 | slug(article.title) |
| 通讯录按拼音排序 | sorted(contacts, key=lambda c: sort_key(c.name)) |
| 中文检索索引 | 同时索引原文与 convert(text, style='plain') |
| 汉字教学注音 | convert(text, style='zhuyin') |
| 数据清洗规范化 | initials() 生成缩写列 |
| 离线内网服务 | 直接拷贝 hantone/ 目录,无需联网装包 |
📷 运行截图与演示动图占位 —— 欢迎社区贡献 PR 补充。
hantone/
├── __init__.py 公共 API 门面
├── _data.py 压缩内嵌的拼音数据表(自动生成)
├── _table.py 数据加载与查询(惰性解压)
├── style.py 风格渲染(标调规则 / 注音符号)
├── rules.py 消歧规则库(词组 / 姓氏 / 音变)
├── core.py 核心转换引擎(最长匹配 + 音变 + 排版)
├── cli.py 命令行界面
└── __main__.py python -m hantone
1. 为什么读音来源要分优先级?
Unihan 的 kHanyuPinyin(《汉语大字典》)收录极全但含大量古音,直接用会让「行」冒出 hàng、xìng 这类现代罕用读音。HanTone 改用《通用规范汉字表》(2013) 优先,保证输出的是现代规范普通话。
2. 为什么词组规则要被「保护」?
早期版本让轻声规则作用于所有音节,结果「快乐」变成 kuài le、「厦门」变成 xià men。修正方案是给规则读音打上锁定标记,自动音变只作用于未锁定的音节。
3. 为什么变调默认关闭?
拼音标注的通行做法是标本调(「你好」写作 nǐ hǎo)。口语变调属于进阶需求,因此做成 sandhi=True 可选项。
4. 为什么坚持零依赖?
拼音是基础设施级能力。它若引入依赖,会让离线环境、内网部署、嵌入式场景全部失效。数据用 zlib + base85 内嵌,是体积与自包含性的最佳平衡。
最欢迎的三类 PR:
本项目属于工具库 / 命令行工具类型,无需上传 Release 二进制包,按以下方式集成即可。
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make test # 运行 34 项单元测试
make demo # 功能演示
# Unix / macOS / WSL
./build.sh build
# Windows
build.bat build
# 或使用标准工具链
python -m build
产物位于 dist/:hantone-1.0.0.tar.gz 与 hantone-1.0.0-py3-none-any.whl。
| 🎯 方式 | 📝 命令 | ✅ 适用 |
|---|---|---|
| PyPI 安装 | pip install hantone |
常规项目 |
| Wheel 离线安装 | pip install hantone-1.0.0-py3-none-any.whl |
内网环境 |
| 源码内嵌 | 拷贝 hantone/ 目录到项目 |
零依赖打包 / 嵌入式 |
| 容器镜像 | COPY hantone/ /app/hantone/ |
Docker 部署 |
curl -O https://www.unicode.org/Public/UCD/latest/ucd/Unihan.zip
unzip Unihan.zip
python tools/build_data.py Unihan_Readings.txt hantone/_data.py
_data.py 约 500 KB,属生成产物但必须随包分发,请勿从仓库移除。feat: / fix: / docs: / refactor: / test: / chore:make test 全绿提交 Issue 时请附:HanTone 版本、Python 版本、可复现的最小输入与期望/实际输出。
本项目采用 MIT 开源协议,详见 LICENSE。
数据说明:内置汉字读音表由本项目依据 Unicode 官方 Unihan 数据库(Unihan_Readings.txt,Unicode License)经归一化与规范优先级合并后重新编码生成,属事实性语言数据。
HanTone 是一套零第三方依賴、完全離線的漢字拼音轉換引擎,以純 Python 標準函式庫實作。
它要解決的並不是「把漢字查表換成拼音」這種簡單問題,而是中文處理裡最容易出錯的那一件事——多音字。
多數拼音工具只在單字層面運作,於是「銀行」被讀成
yín xíng、「重慶」被讀成zhòng qìng。 HanTone 在詞組層面進行消歧,因此yín háng與chóng qìng才是它的答案。
| 😖 痛點 | ✨ HanTone 的解法 |
|---|---|
| 「銀行 / 行走」讀音不分 | 🎯 405 條詞組級消歧規則,最長正向匹配 |
| 「重慶 / 重要」地名讀錯 | 🗺️ 內建地名專用讀音(重慶、廈門、六安、麗水……) |
| 姓氏「單 / 仇 / 查」讀錯 | 👤 mode='surname' 姓氏模式,含 59 條複姓規則 |
| Python 中文排序不符合習慣 | 🔤 sort_key() 依拼音排序,而非 Unicode 碼位 |
| 「一 / 不」的變調不會標 | 🗣️ sandhi=True 開啟口語變調與三聲變調 |
| 需要注音符號教學 | 🎵 內建 ㄅㄆㄇㄈ 注音符號(Bopomofo)輸出 |
| 離線環境 / 內網無法裝套件 | 📦 零依賴,只用一個 .py 套件,斷網照跑 |
kuài lè 而不是 kuài le。sorted(names, key=hantone.sort_key)slug('漢語拼音') → han-yu-pin-yinheteronym() 列出全部讀音,explain() 附帶英文釋義pinyin / slug / initials / sort / lookup / info 六個子命令zlib / base64 / argparse / unicodedata# 方式一:從原始碼安裝(推薦)
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make install # 等同於 pip install -e .
# 方式二:直接用 PyPI 套件
pip install hantone
# 方式三:零安裝 —— 把 hantone/ 目錄複製進你的專案即可
import hantone
hantone.convert('中国银行') # => 'zhōng guó yín háng'
hantone.convert('重庆') # => 'chóng qìng'
hantone.convert('音乐') # => 'yīn yuè'
python -m hantone pinyin 中国银行
# zhōng guó yín háng
python -m hantone pinyin 好好学习 --sandhi
# háo hǎo xué xí
python -m hantone slug 汉语拼音转换引擎
# han-yu-pin-yin-zhuan-huan-yin-qing
python -m hantone sort 张三 李四 王五 赵六
# 李四 / 王五 / 张三 / 赵六
python -m hantone lookup 行
convert()import hantone
hantone.convert('中华人民共和国')
# 'zhōng huá rén mín gòng hé guó'
hantone.convert('你好,世界!')
# 'nǐ hǎo,shì jiè!' ← 標點兩側自動不加多餘空格
hantone.convert('中国 ABC 2026')
# 'zhōng guó ABC 2026' ← 英文與數字保持原樣
參數說明
| 參數 | 預設值 | 說明 |
|---|---|---|
style |
'mark' |
輸出風格,見下表 |
separator |
' ' |
分隔符號;非空格時對所有片段統一連接 |
mode |
'normal' |
'surname' 啟用姓氏讀音 |
sandhi |
False |
True 啟用口語變調(預設輸出規範本調) |
erhua |
False |
True 合併詞尾兒化音 |
errors |
'default' |
'ignore' 丟棄非漢字;'keep' 保留 |
text = '中华人民共和国'
hantone.convert(text, style='mark') # 'zhōng huá rén mín gòng hé guó' 聲調符號
hantone.convert(text, style='number') # 'zhong1 hua2 ren2 min2 gong4 he2 guo2'
hantone.convert(text, style='plain') # 'zhong hua ren min gong he guo'
hantone.convert(text, style='initial') # 'zh h r m g h g' 聲母
hantone.convert(text, style='first') # 'z h r m g h g' 首字母
hantone.convert(text, style='zhuyin') # 'ㄓㄨㄥ ㄏㄨㄚˊ ㄖㄣˊ ㄇㄧㄣˊ ㄍㄨㄥˋ ㄏㄜˊ ㄍㄨㄛˊ'
hantone.convert('银行') # 'yín háng' ✅ 不是 yín xíng
hantone.convert('行走') # 'xíng zǒu'
hantone.convert('重庆') # 'chóng qìng' ✅ 不是 zhòng qìng
hantone.convert('重要') # 'zhòng yào'
hantone.convert('音乐') # 'yīn yuè'
hantone.convert('快乐') # 'kuài lè' ✅ 輕聲規則不會誤傷
hantone.convert('厦门') # 'xià mén'
hantone.convert('六安') # 'lù ān'
hantone.convert('出差') # 'chū chāi'
hantone.convert('下载') # 'xià zài'
hantone.convert('单') # 'dān'
hantone.convert('单', mode='surname') # 'shàn' ✅
hantone.convert('仇', mode='surname') # 'qiú'
hantone.convert('查', mode='surname') # 'zhā'
hantone.convert('曾', mode='surname') # 'zēng'
hantone.convert('解', mode='surname') # 'xiè'
hantone.convert('尉迟', mode='surname') # 'yù chí' ✅ 複姓
hantone.convert('万俟', mode='surname') # 'mò qí'
預設輸出《漢語拼音方案》規範本調;需要口語實際讀音時開啟 sandhi=True。
hantone.convert('你好') # 'nǐ hǎo' 規範本調
hantone.convert('你好', sandhi=True) # 'ní hǎo' 三聲變調 ✅
hantone.convert('一个') # 'yī gè'
hantone.convert('一个', sandhi=True) # 'yí gè' 「一」在四聲前變二聲 ✅
hantone.convert('一天', sandhi=True) # 'yì tiān' 「一」在一聲前變四聲 ✅
hantone.convert('不是') # 'bù shì'
hantone.convert('不是', sandhi=True) # 'bú shì' 「不」在四聲前變二聲 ✅
hantone.convert('妈妈', sandhi=True) # 'mā ma' 疊詞輕聲 ✅
⚠️ 注意:詞組規則中已明確標註的讀音不會被變調改寫, 因此
hantone.convert('快乐', sandhi=True)仍然是kuài lè。
# 依拼音排序中文(修正 Unicode 碼位排序的不直覺)
names = ['张三', '李四', '王五', '赵六']
sorted(names, key=hantone.sort_key)
# ['李四', '王五', '张三', '赵六']
# 產生 URL 友善別名
hantone.slug('汉语拼音转换引擎') # 'han-yu-pin-yin-zhuan-huan-yin-qing'
hantone.slug('汉语拼音', separator='_') # 'han_yu_pin_yin'
hantone.slug('汉语拼音', tone=True) # 'han4-yu3-pin1-yin1'
# 首字母縮寫
hantone.initials('中国银行') # 'zgyh'
hantone.initials('中国银行', style='initial') # 'zhgyh' 完整聲母
hantone.heteronym('行') # [['xíng', 'háng', 'héng']]
hantone.explain('中')
# {'char': '中', 'code_point': 'U+4E2D',
# 'pinyin': ['zhōng', 'zhòng'],
# 'zhuyin': ['ㄓㄨㄥ', 'ㄓㄨㄥˋ'],
# 'meaning': 'central; center, middle; in the midst of; hit (target); attain',
# 'heteronym': True}
hantone.hanzi_count() # 44364
hantone.syllable_count() # 1456
python -m hantone pinyin [文本...] [-s STYLE] [-d SEP] [--mode] [--sandhi] [--erhua] [--stdin]
python -m hantone slug [文本...] [-d SEP] [--tone] [--stdin]
python -m hantone initials [文本...] [--full] [--stdin]
python -m hantone sort [条目...] [--no-tone] [--stdin]
python -m hantone lookup 漢字 [-s STYLE]
python -m hantone info
管線用法:
echo 重庆银行 | python -m hantone pinyin --stdin
# chóng qìng yín háng
cat names.txt | python -m hantone sort --stdin
| 🏷️ 場景 | 💻 用法 |
|---|---|
| 部落格 URL 產生 | slug(article.title) |
| 通訊錄依拼音排序 | sorted(contacts, key=lambda c: sort_key(c.name)) |
| 中文檢索索引 | 同時索引原文與 convert(text, style='plain') |
| 漢字教學注音 | convert(text, style='zhuyin') |
| 資料清理正規化 | initials() 產生縮寫欄位 |
| 離線內網服務 | 直接複製 hantone/ 目錄,無需連網裝套件 |
📷 執行截圖與示範動畫預留位置 —— 歡迎社群貢獻 PR 補充。
hantone/
├── __init__.py 公共 API 門面
├── _data.py 壓縮內嵌的拼音資料表(自動產生)
├── _table.py 資料載入與查詢(惰性解壓)
├── style.py 風格渲染(標調規則 / 注音符號)
├── rules.py 消歧規則庫(詞組 / 姓氏 / 音變)
├── core.py 核心轉換引擎(最長匹配 + 音變 + 排版)
├── cli.py 命令列介面
└── __main__.py python -m hantone
1. 為什麼讀音來源要分優先順序?
Unihan 的 kHanyuPinyin(《漢語大字典》)收錄極全但含大量古音,直接用會讓「行」冒出 hàng、xìng 這類現代罕用讀音。HanTone 改以《通用規範漢字表》(2013) 優先,保證輸出的是現代規範普通話。
2. 為什麼詞組規則要被「保護」?
早期版本讓輕聲規則作用於所有音節,結果「快樂」變成 kuài le、「廈門」變成 xià men。修正方案是給規則讀音加上鎖定標記,自動音變只作用於未鎖定的音節。
3. 為什麼變調預設關閉?
拼音標註的通行做法是標本調(「你好」寫作 nǐ hǎo)。口語變調屬進階需求,因此做成 sandhi=True 選項。
4. 為什麼堅持零依賴?
拼音是基礎設施級能力。它若引入依賴,會讓離線環境、內網部署、嵌入式場景全部失效。資料用 zlib + base85 內嵌,是體積與自包含性的最佳平衡。
最受歡迎的三類 PR:
本專案屬於工具庫 / 命令列工具類型,無需上傳 Release 二進位檔,依下列方式整合即可。
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make test # 執行 34 項單元測試
make demo # 功能示範
# Unix / macOS / WSL
./build.sh build
# Windows
build.bat build
# 或使用標準工具鏈
python -m build
產物位於 dist/:hantone-1.0.0.tar.gz 與 hantone-1.0.0-py3-none-any.whl。
| 🎯 方式 | 📝 命令 | ✅ 適用 |
|---|---|---|
| PyPI 安裝 | pip install hantone |
常規專案 |
| Wheel 離線安裝 | pip install hantone-1.0.0-py3-none-any.whl |
內網環境 |
| 原始碼內嵌 | 複製 hantone/ 目錄到專案 |
零依賴打包 / 嵌入式 |
| 容器映像 | COPY hantone/ /app/hantone/ |
Docker 部署 |
curl -O https://www.unicode.org/Public/UCD/latest/ucd/Unihan.zip
unzip Unihan.zip
python tools/build_data.py Unihan_Readings.txt hantone/_data.py
_data.py 約 500 KB,屬產生結果但必須隨套件散布,請勿從儲存庫移除。feat: / fix: / docs: / refactor: / test: / chore:make test 全數通過提交 Issue 時請附:HanTone 版本、Python 版本、可重現的最小輸入與期望/實際輸出。
本專案採用 MIT 開源協議,詳見 LICENSE。
資料說明:內建漢字讀音表由本專案依據 Unicode 官方 Unihan 資料庫(Unihan_Readings.txt,Unicode License)經正規化與規範優先順序合併後重新編碼產生,屬事實性語言資料。
HanTone is a zero-dependency, fully offline Mandarin Pinyin conversion engine written against nothing but the Python standard library.
It is not trying to solve the easy problem of "look a character up in a table". It is aimed squarely at the thing that actually breaks Chinese text processing — heteronyms, characters with more than one reading.
Most Pinyin tools operate at the single-character level, which is why 银行 comes out as
yín xínginstead ofyín háng, and 重庆 aszhòng qìnginstead ofchóng qìng. HanTone disambiguates at the phrase level, soyín hángandchóng qìngare what you get.
| 😖 Problem | ✨ How HanTone fixes it |
|---|---|
| 银行 / 行走 sound identical | 🎯 405 phrase-level disambiguation rules, longest-match-first |
| Place names misread (重庆 / 重要) | 🗺️ Dedicated toponym readings: 重庆, 厦门, 六安, 丽水 … |
| Surnames misread (单 / 仇 / 查) | 👤 mode='surname' with 59 rules including compound surnames |
| Python sorts Chinese unintuitively | 🔤 sort_key() sorts by Pinyin, not by Unicode code point |
| No tone sandhi for 一 and 不 | 🗣️ sandhi=True enables spoken-form tone sandhi |
| Need Bopomofo for teaching | 🎵 Built-in ㄅㄆㄇㄈ Zhuyin output |
| Air-gapped / no-pip environments | 📦 Zero dependencies, one .py package, works offline |
kuài lè, never kuài le.sorted(names, key=hantone.sort_key)slug('汉语拼音') → han-yu-pin-yinheteronym() lists every reading, explain() adds English glossespinyin / slug / initials / sort / lookup / infozlib / base64 / argparse / unicodedata# Option 1: from source (recommended)
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make install # equivalent to: pip install -e .
# Option 2: from PyPI
pip install hantone
# Option 3: no install at all — just drop the hantone/ folder into your project
import hantone
hantone.convert('中国银行') # => 'zhōng guó yín háng'
hantone.convert('重庆') # => 'chóng qìng'
hantone.convert('音乐') # => 'yīn yuè'
python -m hantone pinyin 中国银行
# zhōng guó yín háng
python -m hantone pinyin 好好学习 --sandhi
# háo hǎo xué xí
python -m hantone slug 汉语拼音转换引擎
# han-yu-pin-yin-zhuan-huan-yin-qing
python -m hantone sort 张三 李四 王五 赵六
# 李四 / 王五 / 张三 / 赵六
python -m hantone lookup 行
convert()import hantone
hantone.convert('中华人民共和国')
# 'zhōng huá rén mín gòng hé guó'
hantone.convert('你好,世界!')
# 'nǐ hǎo,shì jiè!' <- no stray spaces around punctuation
hantone.convert('中国 ABC 2026')
# 'zhōng guó ABC 2026' <- Latin text and digits pass through
Parameters
| Parameter | Default | Meaning |
|---|---|---|
style |
'mark' |
Output style (see below) |
separator |
' ' |
Join separator; non-space values join every token uniformly |
mode |
'normal' |
'surname' enables surname readings |
sandhi |
False |
True applies spoken tone sandhi (default is citation tone) |
erhua |
False |
True merges trailing 儿 into the previous syllable |
errors |
'default' |
'ignore' drops non-hanzi; 'keep' preserves them |
text = '中华人民共和国'
hantone.convert(text, style='mark') # 'zhōng huá rén mín gòng hé guó' tone marks
hantone.convert(text, style='number') # 'zhong1 hua2 ren2 min2 gong4 he2 guo2'
hantone.convert(text, style='plain') # 'zhong hua ren min gong he guo'
hantone.convert(text, style='initial') # 'zh h r m g h g' initials
hantone.convert(text, style='first') # 'z h r m g h g' first letters
hantone.convert(text, style='zhuyin') # 'ㄓㄨㄥ ㄏㄨㄚˊ ㄖㄣˊ ㄇㄧㄣˊ ㄍㄨㄥˋ ㄏㄜˊ ㄍㄨㄛˊ'
hantone.convert('银行') # 'yín háng' ✅ not yín xíng
hantone.convert('行走') # 'xíng zǒu'
hantone.convert('重庆') # 'chóng qìng' ✅ not zhòng qìng
hantone.convert('重要') # 'zhòng yào'
hantone.convert('音乐') # 'yīn yuè'
hantone.convert('快乐') # 'kuài lè' ✅ neutral-tone rules don't corrupt it
hantone.convert('厦门') # 'xià mén'
hantone.convert('六安') # 'lù ān'
hantone.convert('出差') # 'chū chāi'
hantone.convert('下载') # 'xià zài'
hantone.convert('单') # 'dān'
hantone.convert('单', mode='surname') # 'shàn' ✅
hantone.convert('仇', mode='surname') # 'qiú'
hantone.convert('查', mode='surname') # 'zhā'
hantone.convert('曾', mode='surname') # 'zēng'
hantone.convert('解', mode='surname') # 'xiè'
hantone.convert('尉迟', mode='surname') # 'yù chí' ✅ compound surname
hantone.convert('万俟', mode='surname') # 'mò qí'
By default HanTone emits citation tones as prescribed by the Hanyu Pinyin Fang'an. Pass sandhi=True for the way people actually say it.
hantone.convert('你好') # 'nǐ hǎo' citation tone
hantone.convert('你好', sandhi=True) # 'ní hǎo' third-tone sandhi ✅
hantone.convert('一个') # 'yī gè'
hantone.convert('一个', sandhi=True) # 'yí gè' 一 → 2nd before a 4th ✅
hantone.convert('一天', sandhi=True) # 'yì tiān' 一 → 4th before a 1st ✅
hantone.convert('不是') # 'bù shì'
hantone.convert('不是', sandhi=True) # 'bú shì' 不 → 2nd before a 4th ✅
hantone.convert('妈妈', sandhi=True) # 'mā ma' reduplication neutral tone ✅
⚠️ Note: readings explicitly pinned by a phrase rule are never rewritten by sandhi, so
hantone.convert('快乐', sandhi=True)still returnskuài lè.
# Sort Chinese by Pinyin instead of by Unicode code point
names = ['张三', '李四', '王五', '赵六']
sorted(names, key=hantone.sort_key)
# ['李四', '王五', '张三', '赵六']
# URL-friendly slugs
hantone.slug('汉语拼音转换引擎') # 'han-yu-pin-yin-zhuan-huan-yin-qing'
hantone.slug('汉语拼音', separator='_') # 'han_yu_pin_yin'
hantone.slug('汉语拼音', tone=True) # 'han4-yu3-pin1-yin1'
# Acronyms
hantone.initials('中国银行') # 'zgyh'
hantone.initials('中国银行', style='initial') # 'zhgyh' full initials
hantone.heteronym('行') # [['xíng', 'háng', 'héng']]
hantone.explain('中')
# {'char': '中', 'code_point': 'U+4E2D',
# 'pinyin': ['zhōng', 'zhòng'],
# 'zhuyin': ['ㄓㄨㄥ', 'ㄓㄨㄥˋ'],
# 'meaning': 'central; center, middle; in the midst of; hit (target); attain',
# 'heteronym': True}
hantone.hanzi_count() # 44364
hantone.syllable_count() # 1456
python -m hantone pinyin [text...] [-s STYLE] [-d SEP] [--mode] [--sandhi] [--erhua] [--stdin]
python -m hantone slug [text...] [-d SEP] [--tone] [--stdin]
python -m hantone initials [text...] [--full] [--stdin]
python -m hantone sort [items...] [--no-tone] [--stdin]
python -m hantone lookup CHAR [-s STYLE]
python -m hantone info
Piping:
echo 重庆银行 | python -m hantone pinyin --stdin
# chóng qìng yín háng
cat names.txt | python -m hantone sort --stdin
| 🏷️ Scenario | 💻 Usage |
|---|---|
| Blog post slugs | slug(article.title) |
| Sorting a contact list | sorted(contacts, key=lambda c: sort_key(c.name)) |
| Chinese search indexing | Index both the original text and convert(text, style='plain') |
| Teaching materials | convert(text, style='zhuyin') |
| Data normalisation | initials() for abbreviation columns |
| Air-gapped services | Copy the hantone/ folder in — no install, no network |
📷 Screenshots and demo GIF placeholders — community PRs welcome.
hantone/
├── __init__.py public API surface
├── _data.py compressed embedded Pinyin table (generated)
├── _table.py data loading and lookup (lazy decompression)
├── style.py style rendering (tone placement / Zhuyin)
├── rules.py disambiguation rules (phrases / surnames / sandhi)
├── core.py conversion engine (longest match + sandhi + layout)
├── cli.py command-line interface
└── __main__.py python -m hantone
1. Why are reading sources ranked?
Unihan's kHanyuPinyin (Hanyu Da Zidian) is exhaustive but full of archaic readings; using it directly makes 行 sprout hàng and xìng. HanTone prefers the General Standard Chinese Characters (2013) so the output is modern standard Mandarin.
2. Why are phrase rules "protected"?
An early version applied neutral-tone rules to every syllable, turning 快乐 into kuài le and 厦门 into xià men. The fix marks rule-specified readings as locked, so automatic sandhi only touches unlocked syllables.
3. Why is sandhi off by default?
Pinyin annotation conventionally uses the citation tone (你好 is written nǐ hǎo). Spoken sandhi is an advanced need, so it is opt-in via sandhi=True.
4. Why insist on zero dependencies?
Pinyin is infrastructure. If it pulls in dependencies, offline, air-gapped and embedded scenarios all break. zlib + base85 embedded data is the best balance of size and self-containment.
HanTone is a library / CLI tool, so no Release binaries are published — integrate it as follows.
git clone https://github.com/gitstq/HanTone.git
cd HanTone
make test # run 34 unit tests
make demo # feature demo
# Unix / macOS / WSL
./build.sh build
# Windows
build.bat build
# or the standard toolchain
python -m build
Artifacts land in dist/: hantone-1.0.0.tar.gz and hantone-1.0.0-py3-none-any.whl.
| 🎯 Method | 📝 Command | ✅ Best for |
|---|---|---|
| PyPI | pip install hantone |
regular projects |
| Offline wheel | pip install hantone-1.0.0-py3-none-any.whl |
air-gapped networks |
| Vendor the source | copy hantone/ into your project |
dependency-free packaging / embedded |
| Container image | COPY hantone/ /app/hantone/ |
Docker deployments |
curl -O https://www.unicode.org/Public/UCD/latest/ucd/Unihan.zip
unzip Unihan.zip
python tools/build_data.py Unihan_Readings.txt hantone/_data.py
_data.py is roughly 500 KB. It is generated, but it must ship with the package — do not remove it.feat: / fix: / docs: / refactor: / test: / chore:make test greenWhen opening an issue, please include: HanTone version, Python version, and a minimal reproducible input with expected vs. actual output.
Released under the MIT License — see LICENSE.
Data notice: the bundled readings were produced by this project from the Unicode Unihan Database (Unihan_Readings.txt, Unicode License) through normalisation and authority-ordered merging. They are factual linguistic data.
HanTone · 零依赖 · 离线优先 · Zero-dependency & offline-first
如果这个项目帮到了你,欢迎点个 ⭐ Star! If this project helped you, a ⭐ would be much appreciated!
gitstq/HanTone is a public repo on GitHub by gitstq. 🔤 HanTone — 零依赖 · 离线优先的汉字拼音转换引擎 | 多音字词组级消歧 · 注音符号 · 变调 · 中文排序 | Zero-dependency, offline-first Mandarin Pinyin engine.
It declares the MIT license on GitHub.
Its maker tagged it for macOS, Windows and Linux, or as Docker or cross-platform. That is declared by the maker; Take My Repo has not tested it.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-10-31. GitHub counts 0 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
A generative speech model for daily dialogue.
Reverse engineer anything with agents, from app behavior down to native binaries.

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Double bopomo(ẑù-yīn), A Chinese Input Method for Taiwanese, ẑù-yīn users.雙碼注音,給注音使用者的雙拼輸入法。不需要額外學習漢語拼音。如果覺得不錯請幫我多多推廣宣傳。(繁體、中文、雙拼、輸入法、臺灣、正體)
ADB 驱动的 Android 虚拟定位 CLI:常驻推送、坐标系统一换算、GPX 轨迹回放。零 npm 依赖,无需 root。
BlueEagle AI Gateway | 蓝鹰AI网关 - Cheapest AI API Gateway | 0.09x cost | 1:1 recharge | GPT-4o Claude Gemini DeepSeek | OpenAI compatible | 最便宜AI中转站
Cheapest AI API Gateway | GPT-4o/Claude/Gemini at 0.09x cost | 1:1 CNY:USD recharge | 100% official pool | OpenAI compatible | ahg.codes
🔬 HexScope — 零依赖·离线优先的二进制文件取证探查工具箱 | Zero-dependency binary forensics workbench: hex dump, magic detection, entropy, strings, histogram, binary diff & file carving
🔭 零依赖 · 离线优先的 A2A(Agent2Agent)协议一致性审计与互操作性探针引擎:36 条规则、4 种报告格式、CI 门禁就绪
🛡️ AgentCubicle — 零依赖·离线优先的 AI Agent 隔离工作区、动作前置授权与防篡改审计引擎 | Zero-dependency isolated workspaces, pre-action authorization & tamper-evident audit for AI agents
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/gitstq/HanToneTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.