by sysprog21
A linguistic linter for Traditional Chinese (zh-TW)
# Add to your Claude Code skills
git clone https://github.com/sysprog21/zhtw-mcpLast scanned: 5/27/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-27T08:05:37.662Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail · terms & refunds
A linguistic linter for Traditional Chinese (zh-TW) that enforces Taiwan Ministry of Education (MoE) standards on vocabulary, punctuation, and character shapes. It plugs into AI coding assistants through the Model Context Protocol (MCP) and catches Mainland Chinese (zh-CN) regional drift before it reaches the user.
The tool enforces three official Taiwan standards:
Over 1100 vocabulary rules and 15 casing rules are compiled into the binary. For ambiguous terms, the server asks the AI assistant it runs inside for help deciding -- no extra API keys required.
In the late Qing dynasty, scholars had to express Western concepts in a writing system with no native vocabulary for them. Whether coining new words or importing translations via Japanese (和製漢語), they assembled a literary system under enormous time pressure. Many translated terms were inconsistent, ambiguous, or contradictory. The Chinese-speaking world has lived with these deficiencies for over a century.
The PRC simplification effort reduced not just stroke counts but vocabulary precision. Terms that should vary by domain got flattened into single catch-all translations. Many PRC translations were coined hastily: if a term worked in one context, it spread uncritically to others.
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 (遍歷理論) |
Automatically check and correct zh-TW text produced by AI, catching cross-strait terminology leaks:
, . :) that should be full-width (， 。 ：)"" curly quotes replaced with Taiwan-style 「」 corner bracketsThese 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.
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.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.sh | sh
powershell -ExecutionPolicy Bypass -c "irm https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.ps1 | iex"
Requires stable Rust 1.91+.
make
The binary is at target/release/zhtw-mcp.
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).
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.
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.
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.