https://github.com/rajatim/zhtw
簡轉繁台灣用語轉換器 | Simplified to Traditional Chinese (Taiwan) Converter - rajatim 出品
https://github.com/rajatim/zhtw
chinese cli i18n linter localization pre-commit python simplified-chinese taiwan text-processing traditional-chinese
Last synced: 2 months ago
JSON representation
簡轉繁台灣用語轉換器 | Simplified to Traditional Chinese (Taiwan) Converter - rajatim 出品
- Host: GitHub
- URL: https://github.com/rajatim/zhtw
- Owner: rajatim
- License: mit
- Created: 2025-12-25T23:49:33.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T08:34:48.000Z (2 months ago)
- Last Synced: 2026-04-08T10:19:49.788Z (2 months ago)
- Topics: chinese, cli, i18n, linter, localization, pre-commit, python, simplified-chinese, taiwan, text-processing, traditional-chinese
- Language: Python
- Size: 1.13 MB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# ZHTW
**繁體中文** · [English](README.en.md)
[](https://github.com/rajatim/zhtw/actions/workflows/ci.yml)
[](https://codecov.io/gh/rajatim/zhtw)
[](https://pypi.org/project/zhtw/)
[](https://central.sonatype.com/artifact/com.rajatim/zhtw)
[](https://github.com/rajatim/homebrew-tap)
[](https://pypi.org/project/zhtw/)
[](https://www.python.org/downloads/)
[](https://adoptium.net/)
[](LICENSE)
**讓你的程式碼說台灣話** — 專治「許可權」「軟件」等違和用語
```
輸入：服务器上的软件需要优化，用户权限请联系管理员
輸出：伺服器上的軟體需要最佳化，使用者權限請聯絡管理員
```
一行程式、一個 CLI、六種 SDK —— 把簡體轉成**真正的台灣繁體**。
---
## 為什麼選 ZHTW？
> **寧可少轉，不要錯轉**
通用轉換工具會過度轉換，把台灣正確的詞也改掉。我們不一樣：**只轉確定要改的詞，其他一律不動。**
| | |
|------|------|
| **零誤判** | 31,000+ 詞條 + 6,360 字元對映，52 本書 1 億字驗證零錯轉 |
| **秒級掃描** | 3,100 KB/s 穩定吞吐，1MB 文字 < 1 秒 |
| **完全離線** | 不傳送任何資料到外部，企業內網也能用 |
| **CI 整合** | 一行指令加入 GitHub Actions，PR 自動檢查 |
| **彈性跳過** | 測試資料、第三方程式碼？標記一下就不會被改 |
### 對比 OpenCC
OpenCC 是通用的繁簡轉換框架，採用「全字元 + 短語替換」策略，規則之間容易互相牴觸，例如 `权→權` 會把「權限」誤轉成「許可權」。ZHTW 專注於**簡體 → 台灣繁體**一個方向，用「詞彙層 + 字元層」分層處理，複合詞上下文優先匹配。
| | OpenCC (s2twp) | ZHTW |
|---|------|------|
| **設計目標** | 通用繁簡多變體轉換 | 簡體 → 台灣繁體 |
| **轉換策略** | 字元 + 短語全量替換 | 詞彙優先 → 字元層補齊 |
| **歧義處理** | 依規則順序 | 102 個歧義字分級管理 + balanced mode 語義消歧 |
| **詞庫規模** | 內建字表 + 短語 | 31,000+ 精選台灣用詞 |
| **誤轉** | `权限 → 許可權` 等常見案例 | 52 本書 1 億字驗證零錯轉 |
| **生態** | C++ 核心、多語言 bindings | CLI + Python/Java/TS/Rust SDK + pre-commit |
想看更多對比案例？執行 `zhtw lookup 权限 服务器 用户`。
---
## 安裝
### macOS (Homebrew) — 推薦
```bash
brew tap rajatim/tap
brew install zhtw
```
更新：`brew upgrade zhtw`
### pip (所有平臺)
```bash
python3 -m pip install zhtw
```
更新：`pip install --upgrade zhtw`
### pipx (隔離環境)
[pipx](https://pipx.pypa.io/) 會在獨立虛擬環境中安裝，不影響系統 Python：
```bash
pipx install zhtw
```
更新：`pipx upgrade zhtw`
### 從原始碼安裝 (開發者)
```bash
git clone https://github.com/rajatim/zhtw.git
cd zhtw
pip install -e ".[dev]"
```
pip 安裝後找不到 zhtw 指令？設定 PATH
```bash
# 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\Scripts
```
---
## 30 秒開始使用
ZHTW 提供三種使用方式，選一個最適合你的場景：
### 1. CLI（命令列）
```bash
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 個檔案）
```
### 2. Python Library
```python
from zhtw import convert
convert("这个软件需要优化")
# → "這個軟體需要最佳化"
```
首次呼叫會載入字典並建立 Aho-Corasick 自動機，後續呼叫會重用快取。進階用法（自訂詞庫、逐行回報、整合到你自己的 pipeline）見 `convert_text` / `Matcher` / `load_dictionary`。詞彙查詢 API：`lookup_word` / `lookup_words`（v3.3.0+）。
### 3. Java SDK
**Maven**：
```xml
com.rajatim
zhtw
4.1.0
```
**Gradle (Kotlin DSL)**：
```kotlin
implementation("com.rajatim:zhtw:4.1.0")
```
**Gradle (Groovy DSL)**：
```groovy
implementation 'com.rajatim:zhtw:4.1.0'
```
```java
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`](sdk/java/BENCHMARK.md)。
### 4. TypeScript SDK
**npm / pnpm / yarn**：
```bash
npm install zhtw-js
# 或
pnpm add zhtw-js
yarn add zhtw-js
```
```typescript
import { convert, check, lookup } from 'zhtw-js';
// 快速使用（zero config，內建 default converter）
convert('这个软件需要优化');
// → '這個軟體需要最佳化'
check('用户权限');
// → [{ start, end, source, target }, ...]
lookup('软件');
// → { input, output, changed, details: [...] }
```
**自訂設定**：
```typescript
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。
### 5. Rust SDK
**Cargo (crates.io)**：
```toml
[dependencies]
zhtw = "4.1.0"
```
```rust
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`）。
---
## 多語言 SDK
ZHTW 以 Python 實作為主，並提供原生 Java、TypeScript、Rust SDK。所有 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](#3-java-sdk) | 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](#5-rust-sdk) | — | — | 高效能、嵌入式 | ✅ Stable |
| **WASM** | `npm install zhtw-wasm` | — | — | 瀏覽器、Edge runtime | ✅ Stable |
| **Go** | `go get` | — | — | 微服務、CLI 工具、雲端原生 | 🚧 Planned |
| **C# (.NET)** | NuGet | — | — | ASP.NET、Unity、桌面應用 | 🚧 Planned |
---
## 涵蓋範圍
**31,000+ 精選詞條 + 6,360 字元對映**，涵蓋 IT 科技、醫療、法律、金融、遊戲、電商、學術、日常、地理、港式用語 10+ 領域。轉換由三層架構負責：**詞彙層**（Aho-Corasick 最長匹配）處理複合詞，**balanced defaults 層**（`--ambiguity-mode balanced`）處理 10 個高頻歧義字（几→幾、后→後、里→裡 等）的預設轉換 + protect_terms 例外保護，**字元層**（`str.translate`）補齊剩餘簡體字。102 個一對多歧義字分級管理，不確定就不轉。
詳細的詞庫分類、雙層架構原理、一對多特例、語義衝突處理表，見 [`docs/DICTIONARY-COVERAGE.md`](docs/DICTIONARY-COVERAGE.md)。
---
## CI/CD 整合
### GitHub Actions
加入 GitHub Actions，每個 PR 自動檢查：
```yaml
# .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
```yaml
# .gitlab-ci.yml
chinese-check:
image: python:3.12-slim
script:
- pip install zhtw
- zhtw check . --json
```
有問題就會失敗，再也不怕漏掉。詳細教學請參考 [CI/CD 整合指南](docs/CI-CD-INTEGRATION.md)。
---
## Pre-commit Hook
Commit 前自動擋住問題：
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rajatim/zhtw
rev: v4.1.0 # 使用最新版本
hooks:
- id: zhtw-check # 檢查模式（建議）
# - id: zhtw-fix # 或自動修正模式
```
```bash
pip install pre-commit && pre-commit install
# 之後每次 commit 都會自動檢查
```
進階設定：只檢查特定檔案型別
```yaml
repos:
- repo: https://github.com/rajatim/zhtw
rev: v4.1.0
hooks:
- id: zhtw-check
types: [python, markdown, yaml] # 只檢查這些型別
exclude: ^tests/fixtures/ # 排除測試資料
```
---
## 忽略特定程式碼
測試資料、第三方程式碼不想被轉？用 pragma 標記即可：
```python
# 忽略這一行
test_data = "软件" # zhtw:disable-line
# 忽略下一行
# zhtw:disable-next
legacy_code = "用户信息"
# 忽略整個區塊
# zhtw:disable
test_cases = ["软件", "硬件", "网络"]
# zhtw:enable
```
專案層級的忽略用 `.zhtwignore`（類 `.gitignore` 格式）；完整範例見 [`docs/CLI-ADVANCED.md`](docs/CLI-ADVANCED.md#zhtwignore-忽略檔案)。
---
## 文件
| 文件 | 內容 |
|------|------|
| [`docs/DICTIONARY-COVERAGE.md`](docs/DICTIONARY-COVERAGE.md) | 完整詞庫分類、雙層架構細節、一對多特例、語義衝突處理 |
| [`docs/CLI-ADVANCED.md`](docs/CLI-ADVANCED.md) | 完整 CLI 引數、詞彙查詢（`lookup`）、多編碼支援、自訂詞庫格式 |
| [`docs/CI-CD-INTEGRATION.md`](docs/CI-CD-INTEGRATION.md) | GitHub Actions / GitLab CI / pre-commit 深入設定 |
| [`sdk/java/BENCHMARK.md`](sdk/java/BENCHMARK.md) | Java SDK 效能測試（JMH） |
| [`CHANGELOG.md`](CHANGELOG.md) | 版本歷史 |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 貢獻指南 |
---
## 開發
```bash
pip install -e ".[dev]"
pytest
ruff check .
```
有問題？[開 Issue](https://github.com/rajatim/zhtw/issues) | 想貢獻？[看 Contributing Guide](CONTRIBUTING.md)
---
MIT License | **tim Insight 出品**