ZHTW

繁體中文 · English

AI 寫的中文，zhtw 替你把關。

無論是 Copilot 寫的程式碼、Claude 寫的文件，還是 LLM 翻譯的本地化字串 —— 把「許可權」「軟件」「调用」這類簡體污染自動修成真正的台灣繁體。

一行程式、一個 CLI、六種語言 SDK。

輸入：服务器上的软件需要优化，用户权限请联系管理员
輸出：伺服器上的軟體需要最佳化，使用者權限請聯絡管理員

一行 zhtw scan / zhtw fix 解決 —— 也就是 LLM 給你 100 個檔案後最該做的事。

使用情境

為什麼選 ZHTW？

寧可少轉，不要錯轉

通用轉換工具會過度轉換，把台灣正確的詞也改掉。我們不一樣：只轉確定要改的詞，其他一律不動。

對比 OpenCC

OpenCC 是通用的繁簡轉換框架，採用「全字元 + 短語替換」策略，規則之間容易互相牴觸，例如 权→權 會把「權限」誤轉成「許可權」。ZHTW 專注於簡體 → 台灣繁體一個方向，用「詞彙層 + 字元層」分層處理，複合詞上下文優先匹配。

精準度案例

以下案例來自 2026-07-03 的 500 筆 corpus 競品差異探索。結果：candidate_gap = 0、zhtw_advantage = 308。也就是這批樣本沒有發現「競品符合 expected、ZHTW 不符合」；反而主要暴露通用轉換器容易過度轉換或保留中國用語。

最新 like-for-like 私有集比較中，v4.4.1 為 951/1,008 accepted，目前詞庫為 955/1,008，淨增 4 筆且沒有 accepted regression（約 +0.40 個百分點）。另外 369 筆完整句規則只算已知案例的保守 regression protection，不計為 fresh-blind 泛化提升；這些結果也不構成「市場最準」宣稱。

完整報告見 docs/reports/competitor-diffs-full-2026-07-03.md 與 docs/reports/competitor-advantage-review-2026-07-03.md。

想看更多對比案例？執行 zhtw lookup 权限 服务器 用户。

安裝

macOS (Homebrew) — 推薦

brew tap rajatim/tap
brew install zhtw

更新：brew upgrade zhtw

pip (所有平臺)

python3 -m pip install zhtw

更新：pip install --upgrade zhtw

pipx (隔離環境)

pipx 會在獨立虛擬環境中安裝，不影響系統 Python：

pipx install zhtw

更新：pipx upgrade zhtw

從原始碼安裝 (開發者)

git clone https://github.com/rajatim/zhtw.git
cd zhtw
pip install -e ".[dev]"

# 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（命令列）

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

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：

<dependency>
    <groupId>com.rajatim</groupId>
    <artifactId>zhtw</artifactId>
    <version>4.4.2</version>
</dependency>

Gradle (Kotlin DSL)：

implementation("com.rajatim:zhtw:4.4.2")

Gradle (Groovy DSL)：

implementation 'com.rajatim:zhtw:4.4.2'

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。

4. TypeScript SDK

npm / pnpm / yarn：

npm install zhtw-js
# 或
pnpm add zhtw-js
yarn add zhtw-js

import { 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。

5. Rust SDK

Cargo (crates.io)：

[dependencies]
zhtw = "4.4.2"

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）。

6. Go SDK

go get github.com/rajatim/zhtw/sdk/go/v4@latest

package 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 驗證。

Standalone Binary

不需要 Go 環境，直接下載預編譯 binary：

# 從 GitHub Release 下載（以 macOS arm64 為例）
curl -sL https://github.com/rajatim/zhtw/releases/download/sdk%2Fgo%2Fv4.4.2/zhtw-darwin-arm64.tar.gz | tar xz
./zhtw convert "软件测试"
# → 軟體測試

# 或透過 go install
go install github.com/rajatim/zhtw/sdk/go/v4/cmd/zhtw@latest

7. C# (.NET) SDK

NuGet：

dotnet add package Zhtw

using 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 驗證。

多語言 SDK

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 效能基準

247 字簡體輸入，10,000 次暖機迭代，Apple Silicon 測量：

所有 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。

CI/CD 整合

GitHub Actions

加入 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

# .gitlab-ci.yml
chinese-check:
  image: python:3.12-slim
  script:
    - pip install zhtw
    - zhtw check . --json

有問題就會失敗，再也不怕漏掉。詳細教學請參考 CI/CD 整合指南。

Pre-commit Hook

Commit 前自動擋住問題：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rajatim/zhtw
    rev: v4.4.2  # 使用最新版本
    hooks:
      - id: zhtw-check   # 檢查模式（建議）
      # - id: zhtw-fix   # 或自動修正模式

pip install pre-commit && pre-commit install
# 之後每次 commit 都會自動檢查

repos:
  - repo: https://github.com/rajatim/zhtw
    rev: v4.4.2
    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。

文件

開發

pip install -e ".[dev]"
pytest
ruff check .

有問題？開 Issue | 想貢獻？看 Contributing Guide

MIT License | tim Insight 出品