AI models amplify the problem

AI language models learn from web text where Simplified Chinese vastly outweighs Traditional Chinese (roughly 2.6:1 in CC-100). Major datasets like CulturaX do not even track Traditional Chinese separately. A FAccT 2025 study confirmed that most models favor zh-CN terminology when asked to write zh-TW. The output looks plausible but is not how people in Taiwan actually write.

This goes beyond character conversion. The same word often means different things across the strait:

| English | zh-CN | zh-TW | Why it matters | |---------|-------|-------|----------------| | concurrency | 並發 | 並行 | In zh-CN, 並行 means "parallel" -- a different concept entirely | | parallel | 並行 | 平行 | zh-CN 並行 = "parallel"; in Taiwan, 並行 = "concurrent" | | process (OS) | 進程 | 行程 | 進程 in Taiwan means "progress," not an OS process | | file / document | 文件 / 文檔 | 檔案 / 文件 | 文件 in China = "file"; in Taiwan = "document" | | render | 渲染 | 算繪 | 渲染 in Taiwan = "exaggerate" (a painting technique) | | traverse | 遍歷 | 走訪 | 遍歷 in Taiwan is reserved for Ergodic theory (遍歷理論) |

What this project does

Automatically check and correct zh-TW text produced by AI, catching cross-strait terminology leaks:

• Half-width punctuation (, . :) that should be full-width (， 。 ：)
• Mainland-style "" curly quotes replaced with Taiwan-style 「」 corner brackets
• Missing or extra CJK-Latin/digit spacing
• Mainland vocabulary -- 軟件→軟體, 內存→記憶體, 默認→預設, etc.
• Non-standard character variants -- 裏→裡, 着→著 per MoE standard forms
• Politically colored terms -- 祖國, 內地
• Casing -- JavaScript, GitHub, macOS

These standards are enforced through two profiles on the strictness axis, plus orthogonal capability flags:

| Profile | Purpose | |---------|---------| | base | Cross-strait vocabulary, punctuation, casing, grammar, politically colored terms | | strict | Full MoE enforcement: character variants (裏→裡), grammar (臺/台), all punctuation |

| Flag | Purpose | |------|---------| | relaxed | Relaxed for software UI: disables colon/dunhao enforcement and grammar checks; uses en-dash for ranges | | detect_ai | AI writing review: filler phrase detection, semantic safety words, copula/passive voice checks, density-based pattern detection |

Profiles control how strict the zh-TW norm enforcement is. Flags are orthogonal -- detect_ai works with either profile, relaxed can combine with strict if you want variant normalization but lenient punctuation.

See docs/rules.md for the full rule reference.

Naming convention: cn and tw

This project follows BCP 47. The region subtag comes from ISO 3166-1 alpha-2, where "region" can denote a sovereign state, territory, or economic area -- not necessarily a "country."

• zh-CN: Chinese as written in the CN region (Simplified)
• zh-TW: Chinese as written in the TW region (Traditional)

Throughout the codebase, cn and tw denote regional writing conventions, not a political statement.

Getting started

Pre-built binaries

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.ps1 | iex"

Building from source

Requires stable Rust 1.91+.

make

The binary is at target/release/zhtw-mcp.

Installing

The quickest way to build, install to ~/.local/bin, and register with Claude Code:

make install      # build release, install binary, register MCP server
make uninstall    # remove binary and MCP registration
make status       # check binary, process, and registration state

For manual setup or other MCP clients:

# Claude Code
claude mcp add zhtw-mcp -- /path/to/zhtw-mcp

# OpenCode
opencode mcp add zhtw-mcp /path/to/zhtw-mcp

Codex CLI or other MCP clients -- add to .mcp.json in your project root:

{
  "mcpServers": {
    "zhtw-mcp": {
      "command": "/path/to/zhtw-mcp",
      "args": []
    }
  }
}

Replace /path/to/zhtw-mcp with the actual binary path (e.g., target/release/zhtw-mcp).

CLI quick start

zhtw-mcp lint README.md                 # lint a file
zhtw-mcp lint file.md --fix             # auto-fix in place
zhtw-mcp lint file.md --fix --dry-run   # preview fixes
zhtw-mcp lint file.md --telemetry       # print stderr summary counters
zhtw-mcp cache clear                    # clear persistent judgment cache

See docs/cli.md for the full CLI reference and docs/mcp.md for MCP tool/resource/prompt details.

Common prompts

When running as an MCP server, you interact through natural language. The assistant translates your intent into zhtw tool calls:

| Intent | Say | Maps to | What happens | |--------|-----|---------|--------------| | Lint text | "Check this paragraph for mainland terms" | zhtw({ "text": "..." }) | Returns issues with line/column, suggestions, and rule type | | Auto-fix | "Fix the zh-TW issues in this document" | zhtw({ "text": "...", "fix_mode": "lexical_safe" }) | Deterministic fixes applied; corrected text returned | | Quality gate | "Reject if more than 3 zh-TW errors" | zhtw({ "text": "...", "max_errors": 3 }) | accepted: true/false verdict based on error count | | Strict MoE | "Check this with strict MoE rules" | zhtw({ "text": "...", "profile": "strict" }) | Adds character variant (裏→裡) and full punctuation enforcement | | UI strings | "Lint this UI string, skip grammar" | zhtw({ "text": "...", "relaxed": true }) | Disables colon/dunhao/grammar enforcement; uses en-dash for ranges | | AI writing review | "Review this for AI writing artifacts" | zhtw({ "text": "...", "detect_ai": true }) | Flags filler phrases, semantic safety words, copula/passive overuse | | Markdown-aware | "Lint this markdown, skip code blocks" | zhtw({ "text": "...", "content_type": "markdown" }) | Fenced code, inline code, and HTML blocks excluded from scanning | | Cost telemetry | "Lint this and include telemetry" | zhtw({ "text": "...", "include_telemetry": true }) | Returns estimated token/caching metrics for the call |

Each zhtw call is stateless -- parameters like profile are per-call, not session state. Omitting profile defaults to base.

The server also exposes two read-only resources for assistants to consult: zh-tw://style-guide/moe (MoE standards) and zh-tw://dictionary/ambiguous (cross-strait term disambiguation). See docs/mcp.md for the full prompt catalog.

Further reading

• docs/cli.md -- full CLI reference, config files, CI/CD integration, S2T conversion
• docs/mcp.md -- MCP tool parameters, resources, prompts, sampling, usage examples
• docs/internals.md -- processing pipeline, script detection, design decisions, testing
• docs/rules.md -- rule type reference, extending the ruleset, runtime overrides
• docs/release.md -- cargo-dist release workflow, upgrading, custom build setup

License

zhtw-mcp is available under a permissive MIT-style license. Use of this source code is governed by a MIT license that can be found in the LICENSE file.