Gukhanmun 0.2.0: Open Korean Dictionary, parenthetical collapsing, proper name grouping, smart numerals

[dahlia]

Gukhanmun is a library and CLI tool for converting Korean text written in mixed hanja/hangul script into consistently annotated output. Academic texts, historical documents, and legal materials routinely mix Chinese characters (hanja) with Korean script (hangul); Gukhanmun reads them and renders the result in your chosen mode: hangul-only, ruby annotation, original script, and more. It is available as a Rust crate, a Node.js package, a WebAssembly module, and a standalone CLI binary.

0.2.0 ships four user-visible improvements: bundled Open Korean Dictionary (우리말샘) support with North Korean readings out of the box, automatic collapsing of redundant inline reading annotations, correct grouping of proper names and unknown multi-character hanja words, and smarter numeral rendering for dates. The playground on the docs site was also significantly upgraded.

Open Korean Dictionary support

The Standard Korean Language Dictionary (標準國語大辭典) that ships with Gukhanmun covers about 260,000 entries, the prescriptive core of South Korean vocabulary. The Open Korean Dictionary, also published by the National Institute of Korean Language, is a far larger, collaboratively edited resource covering technical vocabulary, regional dialects, archaic forms, and, most significantly, North Korean readings. Its general category alone contains roughly 533,000 hanja keys, about twice the coverage of the Standard dictionary.

0.2.0 adds the Open Korean Dictionary as an optional bundled data source, split into four independently composable categories:

• General (一般語): broadest vocabulary coverage, suitable for South Korean text that goes beyond what the Standard dictionary covers
• North Korean (北韓語): approximately 26,000 keys in North Korean orthography, where 歷史 is 력사, 來日 is 래일, and 勞動 is 로동
• Dialect (方言): regional readings
• Archaic (옛말): historical forms

The most immediately visible effect is on the ko-kp preset, which previously had no bundled dictionary at all because the Standard dictionary's South Korean readings are wrong for North Korean text. The ko-kp preset now includes the North Korean category by default, giving it real dictionary support for the first time.

# Before 0.2.0:
echo '歷史的 勞動者' | gukhanmun --preset ko-kp
# 역사적 노동자  (South Korean readings from the fallback phoneticizer)

# 0.2.0:
echo '歷史的 勞動者' | gukhanmun --preset ko-kp
# 력사적 로동자  (North Korean readings from the bundled dictionary)

To disable all bundled dictionaries (Standard and Open Korean Dictionary alike), pass --no-bundled-dictionaries:

echo '自由' | gukhanmun --no-bundled-dictionaries

For JavaScript and TypeScript users, the new @gukhanmun/opendict-fst and @gukhanmun/opendict-cdb packages expose per-category loaders:

import { opendictNorthKoreanFst } from "@gukhanmun/opendict-fst";
import { opendictGeneralCdb }     from "@gukhanmun/opendict-cdb";

JavaScript presets do not auto-load dictionary data; supply the loaders explicitly when you want extended coverage. The dictionary data is distributed under CC BY-SA 2.0 KR, the same license as the Standard dictionary data.

See #5 for the full design rationale and #6 for the implementation.

Redundant parenthetical collapsing

Korean authors writing mixed-script text sometimes include an explicit parenthetical alongside the hanja or hangul: 庫間(곳간) (hanja followed by its hangul reading) or 곳간(庫間) (hangul followed by the hanja equivalent). Before this release, Gukhanmun would convert the hanja and leave the parenthetical alone, producing redundant output like 곳간(곳간) in hangul-only mode:

Input	Mode	Before 0.2.0	0.2.0
庫間(곳간)	hangul-only	곳간(곳간)	곳간(庫間)
곳간(庫間)	hangul-only	곳간(곳간)	곳간(庫間)
庫間(곳간)	original	庫間(곳간)	庫間(곳간) ✓

Gukhanmun now recognises the author's intent and renders the word with both scripts in every rendering mode. Definition glosses such as 庫間(물건을 간직하여 두는 곳) and foreign transliterations such as 蔣介石(장제스) (where 介 does not read 제) pass through untouched.

A parenthetical can also pin an alternative reading for that specific occurrence. 數字(수자) fixes the reading to 수자 (“a few characters”) rather than the Standard dictionary's default 숫자 (“numeral”), even though the collapser would normally select the prescribed spelling.

The feature is on by default. To disable it, pass --no-collapse-parens on the CLI or call Builder::collapse_redundant_parens(false) in Rust. See #3 and #4.

Proper name and multi-character word grouping

When the converter encountered a multi-character hanja word not registered in the dictionary (a personal name, a place name, a technical term), but some of its individual characters happened to have single-character entries in the Standard dictionary, it would annotate each character separately instead of grouping them:

# Before 0.2.0:
echo '洪民憙 部長' | gukhanmun --rendering hangul-hanja-parens
# 홍(洪)민(民)희(憙) 부장(部長)

# 0.2.0:
echo '洪民憙 部長' | gukhanmun --rendering hangul-hanja-parens
# 홍민희(洪民憙) 부장(部長)

The engine now treats single-character dictionary matches that carry no special rendering marks as trivial, and merges them with adjacent fallback segments into a single grouped annotation. Homophone marking still applies correctly across the merged span, and the dictionary provenance is preserved.

This fix applies automatically with no configuration change. See #7 and #8.

Smart numeral defaults

The CLI --numerals option previously defaulted to hangul-phonetic, which renders date numerals phonetically following Korean lexical conventions (六月 as 유월, not 육월). The new default is smart, which substitutes positional Arabic numerals for date-style hanja numeral sequences:

echo '二〇二六年 六月 二〇日' | gukhanmun
# Before: 이공이육년 유월 이공일
# After:  2026년 6월 20일

Words that are ambiguous (a numeral in one reading, a proper name or compound in another), such as 百濟 (Baekje) or 十長生, are left as fallback readings rather than being split into numeric fragments.

To restore the previous phonetic calendar behaviour, pass --numerals hangul-phonetic.

Playground improvements

The playground on the docs site received several upgrades in this cycle:

• A panel below the editor now shows equivalent CLI, Rust, and JavaScript code updated in real time as you adjust settings. When the configuration matches a preset, the snippet uses the preset shortcut rather than spelling out every option individually.
• All four Open Korean Dictionary categories (general, North Korean, dialect, archaic) now have their own toggles alongside the Standard dictionary, and the live conversion updates instantly when you switch them.
• The preset buttons now act as state indicators: a preset lights up whenever the live configuration exactly matches its definition, whether you arrived there by clicking the preset or by adjusting settings by hand.

Orthographic fixes and dictionary updates

• 數字 now correctly reads 숫자, not 수자 (數字 should convert to 숫자, not 수자 #1, Prefer §30 saisiot readings over saisiot-free homographs #2). Both readings appear in the Standard dictionary, but 숫자 is the form mandated by Standard Korean Orthography §30 (한글 맞춤法 第30項), which names six Sino-Korean saisiot (사이시옷) compounds: 곳간, 셋방, 숫자, 찻간, 툇간, 횟수. The dictionary extractor now gives these six forms a dedicated priority tier so the prescribed spelling wins regardless of the order they appear in the source dump.
• Single-hanja foreign-spelling head words such as 元 (위안) and 円 (엔) no longer shadow the Sino-Korean reading of those characters. The engine recovers the original reading from the bundled Unihan data instead.
• The bundled Standard dictionary was regenerated from the 2026-06-06 JSON dump (260,690 entries, up from 260,688).

Upgrading and installing

Upgrading from 0.1.x

Two default behaviours changed in 0.2.0; existing users should be aware of them before upgrading:

• The CLI --numerals default is now smart. If you relied on phonetic calendar readings such as 六月 → 유월, add --numerals hangul-phonetic to restore the previous behaviour. The library preset defaults are unchanged.
• Redundant parenthetical collapsing is on by default across all surfaces. Pass --no-collapse-parens (CLI) or set collapseRedundantParens: false (JavaScript) or call Builder::collapse_redundant_parens(false) (Rust) to opt out.

For Rust users: Annotation is now #[non_exhaustive], so exhaustive pattern matches on it will fail to compile. Add a .. arm or construct new Annotation values from Annotation::default().

The opendict Cargo feature, which bundles the Open Korean Dictionary data (~8 MB), is enabled by default. If binary size or compile time is a concern, disable it explicitly:

cargo add gukhanmun --no-default-features -F stdict

CLI

Install a prebuilt binary with mise:

mise use -g aqua:dahlia/gukhanmun

On Windows, use winget:

winget install HongMinhee.Gukhanmun

Or build from source with Cargo:

cargo install gukhanmun-cli

Prebuilt archives for Linux, macOS, and Windows are attached to the 0.2.0 release on GitHub.

Rust

cargo add gukhanmun

See the Rust installation guide for feature flag options.

JavaScript/TypeScript

# WebAssembly (browsers, Node.js, Deno, Bun):
pnpm add @gukhanmun/wasm @gukhanmun/stdict-fst

# Node-API (Node.js, Deno, Bun; faster on server):
pnpm add @gukhanmun/napi @gukhanmun/stdict-fst

# Optional: Open Korean Dictionary data packages:
pnpm add @gukhanmun/opendict-fst   # or @gukhanmun/opendict-cdb

See the JavaScript installation guide for npm, yarn, Bun, and Deno equivalents.