@dawn-studio/zh-convert

Chinese script conversion for Dawn Studio apps: Simplified ⇄ Traditional (phrase-aware, idempotent), lazy-loaded, never-throw. Extracted from OpenMusic's battle-tested zh-convert + i18n/detect modules.

Default engine: tongwen-core + tongwen-dict (both MIT) — declared as real dependencies, installed automatically. Since 0.5.0 there is also an opt-in OpenCC engine (config-based, see below). This package adds the house layer:

• Lazy, memoized dict loads via dynamic import() — the ~72 KB s2t / ~22 KB t2s tables stay out of the initial bundle, fetched at most once.
• Synchronous handles (s2tConvertLineSync, t2sConvertLineSync) published once warm — no-flash first renders.
• Idempotent s2t merge — tongwen's s2t phrase table is keyed on Simplified, so direct s2t of an already-Traditional 周杰倫 misses the phrase and per-char maps 杰 → 傑 (→ 周傑倫). The merge folds to Simplified first, then per code point keeps the source spelling wherever t2s changed the char.
• Never-throw — any import/build/convert failure degrades to identity, never a throw.
• Japanese guard — the kana/hangul-first classifier means Japanese lines (kana present) are never wrongly Traditionalized.

Install

npm i @dawn-studio/zh-convert

Quick start

import {
  lockScriptSync,   // force one line into a script — the entry point most apps want
  warmScript,       // await dict builds so the first render doesn't flash
  s2tConvertLines,  // batch Simplified → Traditional (position-aligned)
  t2sConvertLines,  // batch Traditional → Simplified
  isChineseLine,    // predicate: safe to convert offline?
  detectLang,       // pure classifier: en | zh-Hant | zh-Hans | ja | ko
  shouldTranslate,  // per-text-unit "should this be translated?" decision
} from '@dawn-studio/zh-convert';

// 1. Warm early (e.g. app boot) when the target is Traditional:
await warmScript('zh-Hant');

// 2. Force any upstream text into the user's script — Chinese only, everything
//    else passes through untouched, never throws, never returns null:
lockScriptSync('周杰伦', 'zh-Hant'); // → '周杰倫'
lockScriptSync('周杰倫', 'zh-Hant'); // → '周杰倫' (idempotent — source spelling kept)
lockScriptSync('こんにちは', 'zh-Hant'); // → 'こんにちは' (Japanese untouched)

Batch conversion (lyrics, search results):

await s2tConvertLines(['头发', '', '简体中文']); // → ['頭髮', '', '簡體中文']
await t2sConvertLines(['止戰之殤']);              // → ['止战之殇']

No-flash sync path for render loops — returns null until warm:

import { warmS2T, s2tConvertLineSync } from '@dawn-studio/zh-convert';
warmS2T(); // fire-and-forget at boot
// ... in render:
const text = s2tConvertLineSync(name) ?? name;

API

OpenCC engine (0.5.0+) — config-based conversion

Modelled on OpenCC's preset config system — the same config names as upstream OpenCC and the online converter (?config=s2t). Implemented with opencc-js (the pure-JavaScript port of OpenCC; dictionaries derived from OpenCC data, MIT AND Apache-2.0) — not the official opencc npm package, which is a native addon and cannot run in browsers or on the edge.

import { convertWithConfig, convertWithConfigSync, warmConfig, OPENCC_CONFIGS } from '@dawn-studio/zh-convert';

await convertWithConfig('鼠标', 's2twp');        // → '滑鼠' (Taiwan phrases)
await convertWithConfig('軟體', 'tw2sp');        // → '软件' (Mainland phrases)
await warmConfig('s2t');                          // warm the sync handle…
convertWithConfigSync('汉字', 's2t');             // → '漢字' (null while cold)

Or route the existing APIs through OpenCC with ConvertOptions:

await s2tConvertLines(['鼠标'], { engine: 'opencc', config: 's2twp' }); // → ['滑鼠']
lockScriptSync('汉字', 'zh-Hant', { engine: 'opencc' }); // sync handle — warmConfig('s2t') first; cold → identity

The default engine stays tongwen; OpenCC is strictly opt-in. The OpenCC path keeps every house guarantee: lazy per-config loading (dynamic import(), never in the initial bundle), never-throw identity fallback, the same Chinese-only guard, and PROTECTED_WORDS protection (占 never becomes 佔 on OpenCC paths either; 占有→佔有 still works).

Config table (upstream OpenCC names ↔ opencc-js locales)

Rough script-lock equivalents: zh-Hant ≈ s2t, zh-Hans ≈ t2s — the regional configs (s2tw, s2hk, …) additionally normalize regional variants/phrases, which the script lock deliberately does not do.

ConvertOptions — every knob, your call

lockScriptSync, s2tConvertLines and t2sConvertLines all accept an optional opts: ConvertOptions. Nothing is hardcoded that a reasonable app would want to change:

import { lockScriptSync, type ConvertOptions } from '@dawn-studio/zh-convert';

// The "Chinese only" rule is just the default guard — replace it freely:
lockScriptSync('こんにちは世界', 'zh-Hant');                                  // → unchanged (default guard)
lockScriptSync('简体', 'zh-Hant', { guard: () => true });                     // → '簡體' (allow all)
lockScriptSync('简体', 'zh-Hant', { guard: (t) => t !== '简体' });            // → '简体' (skip this line)

await s2tConvertLines(['简体', '头发'], { guard: isChineseLine });            // explicit default

Notes

• Engines & attribution: the tongwen dictionaries are MIT (tongwen-core/tongwen-dict); the OpenCC dictionaries come from OpenCC data via opencc-js (opencc-js is MIT AND Apache-2.0; OpenCC data is Apache-2.0). This package itself is Apache-2.0.
• s2t and t2s dicts are built separately — a t2s-only caller never downloads s2t's 148 KB phrase table.
• Deep-imports tongwen-core/esm/* (not the top-level index): the index eval-time references the DOM global NodeFilter and throws where there is no DOM.
• Known ceiling of the default guard: a Japanese line with zero kana (pure kanji) detects as Chinese and will be converted. Override guard if your corpus needs stricter screening.

License

Apache-2.0