繁體中文 · English
讓你的程式碼說台灣話 — 專治「許可權」「軟件」等違和用語
輸入：服务器上的软件需要优化，用户权限请联系管理员
輸出：伺服器上的軟體需要最佳化，使用者權限請聯絡管理員
一行程式、一個 CLI、六種語言 SDK —— 把簡體轉成真正的台灣繁體。
寧可少轉，不要錯轉
通用轉換工具會過度轉換，把台灣正確的詞也改掉。我們不一樣：只轉確定要改的詞，其他一律不動。
| 零誤判 | 31,000+ 詞條 + 6,360 字元對映，52 本書 1 億字驗證零錯轉 |
| 秒級掃描 | 3,100 KB/s 穩定吞吐，1MB 文字 < 1 秒 |
| 完全離線 | 不傳送任何資料到外部，企業內網也能用 |
| CI 整合 | 一行指令加入 GitHub Actions，PR 自動檢查 |
| 彈性跳過 | 測試資料、第三方程式碼？標記一下就不會被改 |
OpenCC 是通用的繁簡轉換框架，採用「全字元 + 短語替換」策略，規則之間容易互相牴觸，例如 权→權 會把「權限」誤轉成「許可權」。ZHTW 專注於簡體 → 台灣繁體一個方向，用「詞彙層 + 字元層」分層處理，複合詞上下文優先匹配。
| OpenCC (s2twp) | ZHTW | |
|---|---|---|
| 設計目標 | 通用繁簡多變體轉換 | 簡體 → 台灣繁體 |
| 轉換策略 | 字元 + 短語全量替換 | 詞彙優先 → 字元層補齊 |
| 歧義處理 | 依規則順序 | 102 個歧義字分級管理 + balanced mode 語義消歧 |
| 詞庫規模 | 內建字表 + 短語 | 31,000+ 精選台灣用詞 |
| 誤轉 | 权限 → 許可權 等常見案例 |
52 本書 1 億字驗證零錯轉 |
| 生態 | C++ 核心、多語言 bindings | CLI + Python/Java/TS/Rust/Go/C# SDK + pre-commit |
想看更多對比案例？執行 zhtw lookup 权限 服务器 用户。
brew tap rajatim/tap
brew install zhtw更新：brew upgrade zhtw
python3 -m pip install zhtw更新：pip install --upgrade zhtw
pipx 會在獨立虛擬環境中安裝，不影響系統 Python：
pipx install zhtw更新：pipx upgrade zhtw
git clone https://github.com/rajatim/zhtw.git
cd zhtw
pip install -e ".[dev]"pip 安裝後找不到 zhtw 指令？設定 PATH
# macOS (zsh)
echo 'export PATH="$PATH:$(python3 -m site --user-base)/bin"' >> ~/.zshrc
source ~/.zshrc
# Linux (bash)
echo 'export PATH="$PATH:~/.local/bin"' >> ~/.bashrc
source ~/.bashrc
# Windows — 通常自動設定，若無請加入環境變數：
# %APPDATA%\Python\PythonXX\ScriptsZHTW 提供三種使用方式，選一個最適合你的場景：
zhtw check . # 檢查整個專案
zhtw check ./file.py # 檢查單一檔案
zhtw fix . # 自動修正
zhtw lookup 软件 服务器 # 查詢：软件→軟體、服务器→伺服器
# Balanced mode：自動消歧 10 個高頻歧義字（几→幾、后→後、里→裡 等）
zhtw fix . --ambiguity-mode balanced輸出範例：
📁 掃描 ./src
📄 src/components/Header.tsx
L12:5: "用户" → "使用者"
📄 src/utils/api.ts
L8:10: "软件" → "軟體"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 發現 2 處需修正（2 個檔案）
from zhtw import convert
convert("这个软件需要优化")
# → "這個軟體需要最佳化"首次呼叫會載入字典並建立 Aho-Corasick 自動機，後續呼叫會重用快取。進階用法（自訂詞庫、逐行回報、整合到你自己的 pipeline）見 convert_text / Matcher / load_dictionary。詞彙查詢 API：lookup_word / lookup_words（v3.3.0+）。
Maven：
<dependency>
<groupId>com.rajatim</groupId>
<artifactId>zhtw</artifactId>
<version>4.3.0</version>
</dependency>Gradle (Kotlin DSL)：
implementation("com.rajatim:zhtw:4.3.0")Gradle (Groovy DSL)：
implementation 'com.rajatim:zhtw:4.3.0'import com.rajatim.zhtw.ZhtwConverter;
// 快速使用（thread-safe singleton）
String result = ZhtwConverter.getDefault().convert("这个软件需要优化");
// → "這個軟體需要最佳化"
// 自訂設定
ZhtwConverter conv = ZhtwConverter.builder()
.sources(List.of("cn", "hk"))
.customDict(Map.of("自定义", "自訂"))
.ambiguityMode("balanced") // 歧義字自動消歧
.build();效能：單句 2μs、100K 字 5.5ms（17.9 MB/s），比 Python 快 ~5.8 倍。詳見 sdk/java/BENCHMARK.md。
npm / pnpm / yarn：
npm install zhtw-js
# 或
pnpm add zhtw-js
yarn add zhtw-jsimport { convert, check, lookup } from 'zhtw-js';
// 快速使用（zero config，內建 default converter）
convert('这个软件需要优化');
// → '這個軟體需要最佳化'
check('用户权限');
// → [{ start, end, source, target }, ...]
lookup('软件');
// → { input, output, changed, details: [...] }自訂設定：
import { createConverter } from 'zhtw-js';
const conv = createConverter({
sources: ['cn'], // 預設 ['cn', 'hk']
customDict: { '自定义': '自訂' }, // 覆蓋內建詞條
ambiguityMode: 'balanced', // 歧義字自動消歧
});
conv.convert('...');特色：isomorphic（Node.js ≥20 + 瀏覽器原生支援）、ESM + CJS 雙產出、零執行期相依、tree-shakeable。所有索引（start / end / position）均為 Unicode codepoint，與 Python CLI、Java SDK 完全 byte-for-byte 一致（共享 sdk/data/golden-test.json 驗證）。釋出走 npm Trusted Publishing (OIDC)，無 long-lived token。
Cargo (crates.io)：
[dependencies]
zhtw = "4.3.0"use zhtw::{AmbiguityMode, Converter, Source};
// Zero config
assert_eq!(zhtw::convert("这个软件需要优化"), "這個軟體需要最佳化");
// Builder with custom dict + balanced mode
let conv = Converter::builder()
.sources([Source::Cn])
.custom_dict([("自定义", "自訂")])
.ambiguity_mode(AmbiguityMode::Balanced) // 歧義字自動消歧
.build()
.expect("non-empty sources");效能：build-time 預編譯 daachorse automaton + phf char map，runtime 零建構成本。詳見 benchmarks（cargo bench -p zhtw）。
go get github.com/rajatim/zhtw/sdk/go/v4@latestpackage main
import (
"fmt"
"github.com/rajatim/zhtw/sdk/go/v4/zhtw"
)
func main() {
// 零設定
fmt.Println(zhtw.Convert("这个软件需要优化"))
// → "這個軟體需要最佳化"
// Builder：自訂詞典 + balanced mode
conv, _ := zhtw.NewBuilder().
Sources(zhtw.SourceCn).
CustomDict(map[string]string{"自定义": "自訂"}).
SetAmbiguityMode(zhtw.AmbiguityBalanced).
Build()
fmt.Println(conv.Convert("自定义几个里程碑"))
}特色：go:embed 內嵌字典、零外部依賴、goroutine-safe。Go 1.21+，支援 go get 直接安裝。所有索引均為 Unicode codepoint，跨 SDK golden-test 驗證。
不需要 Go 環境，直接下載預編譯 binary：
# 從 GitHub Release 下載（以 macOS arm64 為例）
curl -sL https://github.com/rajatim/zhtw/releases/download/sdk%2Fgo%2Fv4.3.0/zhtw-darwin-arm64.tar.gz | tar xz
./zhtw convert "软件测试"
# → 軟體測試
# 或透過 go install
go install github.com/rajatim/zhtw/sdk/go/v4/cmd/zhtw@latestNuGet：
dotnet add package Zhtwusing Zhtw;
// 快速使用（thread-safe singleton）
string result = ZhtwConvert.Convert("这个软件需要优化");
// → "這個軟體需要最佳化"
// Builder：自訂詞典 + balanced mode
var conv = new ConverterBuilder()
.Sources(Source.Cn, Source.Hk)
.CustomDict(new Dictionary<string, string> { ["自定义"] = "自訂" })
.AmbiguityMode(AmbiguityMode.Balanced)
.Build();特色：multi-target netstandard2.0 + net8.0、embedded resource 內嵌字典、零外部依賴（net8.0 以上）。所有索引均為 Unicode codepoint，跨 SDK golden-test 驗證。
ZHTW 以 Python 實作為主，並提供原生 Java、TypeScript、Rust、Go、C# (.NET) 六種語言 SDK；另提供 1 個 WebAssembly 套件（zhtw-wasm）。所有 SDK 共用同一份詞庫資料（zhtw-data.json），轉換結果與 Python CLI 完全一致（跨 SDK 透過共享 sdk/data/golden-test.json 做 byte-for-byte 驗證，零偏差為釋出條件）。所有 SDK 均支援 balanced mode（歧義字自動消歧）。
| SDK | 安裝 | 吞吐量 (1MB) | 單句延遲 | 適用場景 | 狀態 |
|---|---|---|---|---|---|
| Python | pip install zhtw |
3.1 MB/s | — | CLI、CI/CD、pre-commit、資料處理 | ✅ Stable |
| Java | Maven Central | 17.9 MB/s | 2μs | Spring Boot、Android、後端服務 | ✅ Stable |
| TypeScript | npm install zhtw-js |
~16 MB/s | — | Node.js ≥18、瀏覽器（isomorphic ESM+CJS） | ✅ Stable |
| Rust | crates.io | — | — | 高效能、嵌入式 | ✅ Stable |
| WASM | npm install zhtw-wasm |
— | — | 瀏覽器、Edge runtime | ✅ Stable |
| Go | go get |
— | — | 微服務、CLI 工具、雲端原生 | ✅ Stable |
| C# (.NET) | NuGet | — | — | ASP.NET、Unity、桌面應用 | ✅ Stable |
247 字簡體輸入，10,000 次暖機迭代，Apple Silicon 測量：
| SDK | Cold Start (ms) | Avg/op (μs) | Ops/sec | vs Python |
|---|---|---|---|---|
| Rust | 15.4 | 44.5 | 22,470 | 11.3x |
| Go | 43.1 | 45.0 | 22,233 | 11.1x |
| Java | 135.8 | 53.0 | 18,875 | 9.5x |
| C# | 77.5 | 56.2 | 17,786 | 8.9x |
| TypeScript | 168.2 | 62.1 | 16,094 | 8.1x |
| Python | 121.3 | 501.0 | 1,996 | 1.0x |
所有 SDK 輸出完全一致。即使最慢的 Python（0.5ms/次）對 CLI 使用也感覺不到延遲。
31,000+ 精選詞條 + 6,360 字元對映，涵蓋 IT 科技、醫療、法律、金融、遊戲、電商、學術、日常、地理、港式用語 10+ 領域。轉換由三層架構負責：詞彙層（Aho-Corasick 最長匹配）處理複合詞，balanced defaults 層（--ambiguity-mode balanced）處理 10 個高頻歧義字（几→幾、后→後、里→裡 等）的預設轉換 + protect_terms 例外保護，字元層（str.translate）補齊剩餘簡體字。102 個一對多歧義字分級管理，不確定就不轉。
詳細的詞庫分類、雙層架構原理、一對多特例、語義衝突處理表，見 docs/DICTIONARY-COVERAGE.md。
加入 GitHub Actions，每個 PR 自動檢查：
# .github/workflows/chinese-check.yml
name: Chinese Check
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install zhtw
run: pip install zhtw
- name: Check Traditional Chinese
run: zhtw check . --json# .gitlab-ci.yml
chinese-check:
image: python:3.12-slim
script:
- pip install zhtw
- zhtw check . --json有問題就會失敗，再也不怕漏掉。詳細教學請參考 CI/CD 整合指南。
Commit 前自動擋住問題：
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rajatim/zhtw
rev: v4.3.0 # 使用最新版本
hooks:
- id: zhtw-check # 檢查模式（建議）
# - id: zhtw-fix # 或自動修正模式pip install pre-commit && pre-commit install
# 之後每次 commit 都會自動檢查進階設定：只檢查特定檔案型別
repos:
- repo: https://github.com/rajatim/zhtw
rev: v4.3.0
hooks:
- id: zhtw-check
types: [python, markdown, yaml] # 只檢查這些型別
exclude: ^tests/fixtures/ # 排除測試資料測試資料、第三方程式碼不想被轉？用 pragma 標記即可：
# 忽略這一行
test_data = "软件" # zhtw:disable-line
# 忽略下一行
# zhtw:disable-next
legacy_code = "用户信息"
# 忽略整個區塊
# zhtw:disable
test_cases = ["软件", "硬件", "网络"]
# zhtw:enable專案層級的忽略用 .zhtwignore（類 .gitignore 格式）；完整範例見 docs/CLI-ADVANCED.md。
| 文件 | 內容 |
|---|---|
docs/DICTIONARY-COVERAGE.md |
完整詞庫分類、雙層架構細節、一對多特例、語義衝突處理 |
docs/CLI-ADVANCED.md |
完整 CLI 引數、詞彙查詢（lookup）、多編碼支援、自訂詞庫格式 |
docs/CI-CD-INTEGRATION.md |
GitHub Actions / GitLab CI / pre-commit 深入設定 |
sdk/java/BENCHMARK.md |
Java SDK 效能測試（JMH） |
docs/RELEASE-CHECKLIST.md |
版本釋出核對清單 |
CHANGELOG.md |
版本歷史 |
CONTRIBUTING.md |
貢獻指南 |
pip install -e ".[dev]"
pytest
ruff check .有問題？開 Issue | 想貢獻？看 Contributing Guide
MIT License | tim Insight 出品