zhtw-js

Traditional Chinese converter for Taiwan — TypeScript SDK

Simplified Chinese → Taiwan Traditional Chinese converter with zero runtime dependencies. Runs identically in Node.js ≥20 and modern browsers. Byte-for-byte compatible with the Python CLI and Java SDK, verified by a shared golden fixture.

Install

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

Quick start

Zero config — the module exports a ready-to-use default converter:

import { convert, convertJson, check, lookup, explain } from 'zhtw-js';

convert('这个软件需要优化');
// => '這個軟體需要最佳化'

check('用户权限');
// => [{ start, end, source, target }, ...]

lookup('软件');
// => { input, output, changed, details: [...] }

explain('软件');
// => { output: '軟體', events: [...] }

convertJson('{"软件":"这个软件"}');
// => '{"软件":"這個軟體"}' (keys and unrelated bytes stay unchanged)

Advanced: custom converter

import { createConverter } from 'zhtw-js';

const conv = createConverter({
  sources: ['cn'],               // default: ['cn', 'hk']
  customDict: {                  // overrides built-in terms
    '自定义': '自訂',
  },
});

conv.convert('...');
conv.convertJson('{"value":"..."}');
conv.check('...');
conv.lookup('...');
conv.explain('...');

API reference

type Source = 'cn' | 'hk';

interface Match {
  start: number;      // codepoint index, inclusive
  end: number;        // codepoint index, exclusive
  source: string;
  target: string;
}

interface ConversionDetail {
  source: string;
  target: string;
  layer: 'term' | 'char';
  position: number;   // codepoint index
}

interface LookupResult {
  input: string;
  output: string;
  changed: boolean;
  details: ConversionDetail[];
}

interface ExplainEvent {
  rule_id: string;
  layer: 'term' | 'identity' | 'balanced' | 'char';
  outcome: 'applied' | 'protected' | 'skipped';
  input_start: number;
  input_end: number;
  output_start: number;
  output_end: number;
  source: string;
  target: string;
  reason_code: string;
}

interface ExplainResult {
  output: string;
  events: ExplainEvent[];
}

interface ConverterOptions {
  sources?: Source[];                  // default: ['cn', 'hk']
  customDict?: Record<string, string>;
}

interface Converter {
  convert(text: string): string;
  convertJson(text: string): string;
  check(text: string): Match[];
  lookup(word: string): LookupResult;
  explain(text: string): ExplainResult;
}

All start / end / position fields are Unicode codepoint indices, not JavaScript UTF-16 code-unit indices. This keeps cross-SDK output byte-for-byte identical on supplementary-plane characters.

Cross-SDK parity

Every release is verified against sdk/data/golden-test.json and sdk/data/json-adapter-golden.json. The same fixtures are consumed by every SDK. Zero divergence is a release gate.

License

MIT. See LICENSE.

Part of the rajatim/zhtw monorepo.