zhhz

What is zhhz?

zhhz (zh hanzi — 转换汉字, “convert Chinese characters”, a palindrome) is a pure-Rust reimplementation of OpenCC. It converts between Simplified and Traditional Chinese across the same six variants OpenCC supports (Mainland, Taiwan, Hong Kong, Japan old/new), and identifies which variant a piece of text is written in.

All OpenCC dictionaries are embedded at compile time via include_str!, so a single ~1.86 MB static binary (588 KB xz-compressed / 803 KB gzip / 663 KB zstd) carries everything it needs — no runtime data fetch, no separate dictionary directory.

At a glance

# CLI
echo '汉字' | zhhz                # 漢字 (default s2t)
echo '信息' | zhhz -c s2twp       # 資訊 (Taiwan phrases)
echo '鼠标' | zhhz -c s2twp       # 滑鼠

# Rust library
use zhhz::{Config, Converter};
let c = Converter::new(Config::S2t);
assert_eq!(c.convert("汉字"), "漢字");

# Node.js
import { convert, detect, Converter } from "zhhz";
console.log(convert("汉字", "s2t"));            // 漢字
console.log(detect("他去了西維珍尼亞州"));      // { region: "cn-hk", ... }

# Python
import zhhz
print(zhhz.convert("信息", "s2twp"))   # 資訊
print(zhhz.detect("汉字计算机软件"))  # Detection(region='cn-s', confidence=57)

Four distribution channels, one engine

Two numbers worth highlighting:

• t2s via npm/Deno beats the native CLI (~120-125 %): the WASM blob loads the OpenCC dictionaries once and runs in-process — no fork + exec + pipe overhead.
• Deno and Node.js are within 5-10 % of each other for the same WASM blob — V8 is V8, whether it’s running in Node or Deno.

All five share the same Rust conversion core. Conversion output is byte-identical to the OpenCC reference CLI on all 538 supported-config cases. Full perf table: Benchmarks.

Designed for AI agents

zhhz is built first for AI agents (Claude, Cursor, custom LLM pipelines, batch jobs). The CLI is deliberately minimal:

• No TUI, no progress bars, no spinners. Plain text on stdout, errors on stderr.
• stdin / stdout friendly. - means stdin; positional args are files.
• Stable, predictable, safe. Same input → byte-identical output every time.
• No network, no filesystem writes unless asked (--in-place), no temp files.
• Single self-contained binary — drop it in a container and it just works.

What makes zhhz different

• Embedded dictionaries: no data/ directory, no runtime fetch, no marisa-trie to load. Build with include_str! and ship one binary.
• One engine, five channels: the same Rust core produces the CLI binary, the Rust library, the npm WebAssembly artifact, the Python pip install wheel, and the Deno JSR package. No behavioral drift.
• Strict superset of opencc-js: same npm install path, same Converter({from,to}) factory, same custom-words API — plus script-variant detection, introspection (listConfigs / listLocales), and semantic region flags (Converter.forRegion("cn-s", "cn-tw")). See npm API for the full comparison.
• Memory-safe by construction — pure Rust, no unsafe in the conversion core.
• APLv2-licensed, vendored dictionaries from upstream OpenCC.

Where to go next

• Install zhhz — Cargo, npm, pip, direct binary, or build from source
• Live demo — try it in your browser, no install needed
• CLI reference — every flag, every config, examples
• Rust library — embedding zhhz in a Rust project
• Node.js / npm — npm install zhhz, full API reference
• Python integration — pip install zhhz, threading, async-wrap recipe
• Deno integration — npm:zhhz@… (live) + jsr:@ljh-sh/zhhz
• Benchmarks — 5-channel perf table (CLI / npm / Deno / native / Python)
• Why zhhz — design goals, scope, what zhhz is NOT
• FAQ — common questions