Gukhanmun — 한자 혼용 문서를 읽기 쉬운 한글로 바꾸는 오픈소스 도구
한자와 한글이 섞인 문서를 단순 치환이 아니라 한국어 어문 규칙과 문맥을 고려해 변환하는 Rust·JavaScript 라이브러리이자 CLI입니다.
TL;DR
- 한자 혼용 한국어를 한글 전용 텍스트로 변환합니다.
- 대한민국·북한 표기 프리셋과 두음법칙, 숫자, 동음이의어 처리 옵션을 제공합니다.
- 일반 텍스트뿐 아니라 HTML과 마크다운을 구조를 보존하며 처리할 수 있습니다.
- 표준 사전 외에 분야별 사용자 정의 사전을 FST 또는 CDB 형식으로 추가할 수 있습니다.
- 무료 오픈소스 개발 도구로, 오래된 문헌·법률·학술 자료의 전처리에 특히 유용합니다.
핵심 정보
| 항목 | 내용 |
|---|---|
| 서비스 | Gukhanmun |
| 분야 | 개발도구·한국어 자연어 처리 |
| 핵심 용도 | 한자 혼용 한국어를 한글 전용 출력으로 변환 |
| 제공 형태 | CLI, Rust 라이브러리, JavaScript 패키지 |
| 지원 입력 | 일반 텍스트, HTML, 마크다운 |
| 사전 | 표준국어대사전 기반 번들 사전, 사용자 정의 사전 |
| 플랫폼 | 웹 문서, macOS, Linux, Windows |
| 가격 | 무료 오픈소스 |
| 개발 | Dahlia |
| 등록일 | 2026년 6월 16일 |
어떤 문제를 풀까?
한자 혼용 문서를 한글로 바꾸는 일은 글자마다 음을 대응시키는 것보다 복잡합니다. 같은 한자는 단어와 위치에 따라 읽기가 달라지고, 두음법칙이 적용되며, 숫자 한자는 연도·월·수량에 따라 자연스러운 표현이 달라집니다. 동음이의어를 전부 한글로 바꾸면 원문의 뜻을 구별하기 어려워질 수도 있습니다.
Gukhanmun은 이 문제를 사전 검색과 언어 규칙으로 다룹니다. 기본 ko-kr 프리셋은 대한민국 표기와 두음법칙을 적용하고, 문단 단위로 동음이의어 충돌을 살핍니다. ko-kp 프리셋은 북한 표기에 맞춰 두음법칙을 끄는 식입니다. 따라서 역사 자료 디지털화, 법률 문서 검색 색인, 뉴스 아카이브 정리처럼 대량의 혼용문을 일관된 한글 텍스트로 만들어야 할 때 단순 치환기보다 적합합니다.
언어 규칙을 선택하는 변환 엔진
대한민국과 북한 표기 프리셋, 분절 방식, 숫자 및 두음법칙을 세밀하게 조절할 수 있습니다.
공식 문서에서 가장 눈에 띄는 부분은 변환 결과를 조절하는 옵션의 깊이입니다. 기본값인 ko-kr은 번들 표준 사전, 두음법칙, 문단별 동음이의어 판별을 묶어 제공합니다. ko-kp는 북한 표기를 위한 설정입니다. 개별 옵션으로 프리셋의 일부만 덮어쓸 수도 있습니다.
단어 경계를 찾는 방식도 선택할 수 있습니다. lattice는 모든 사전 일치 후보를 동적 계획법으로 평가해 정확도를 우선하고, eager는 왼쪽부터 가장 긴 항목을 택해 속도를 우선합니다. 숫자 처리의 smart 모드는 二〇一六年, 十一月, 一千二百三十四 같은 표현을 각각 2016년, 11월, 1234처럼 문맥에 맞게 바꿉니다. 원음이 필요한 자료라면 한글 음독 방식으로 전환할 수 있습니다.
괄호 속 독음도 무조건 삭제하지 않습니다. 원문 독음과 일치하는 주석은 정리하되, 정의 설명이나 외래 인명 표기는 남깁니다. 한글 독음이 같은 서로 다른 한자어가 한 문맥에 등장하면 필요한 항목에만 한자를 병기할 수 있어, 가독성과 의미 보존 사이의 균형을 잡습니다.
사전과 전문 용어 확장
기본 사전을 자동으로 쓰면서 법률·인명·학술 용어 사전을 우선순위에 따라 추가할 수 있습니다.
대부분의 일반 문서는 번들 사전만으로 시작할 수 있습니다. 하지만 고문헌의 인명, 법률 용어, 회사 내부 명칭은 일반 사전에 없거나 원하는 독음과 다를 수 있습니다. 이때 탭으로 구분한 한자-한글 표를 작성한 뒤 gukhanmun-mkdict로 컴파일해 사용자 정의 사전을 만듭니다.
지원 형식은 FST(.gukfst)와 CDB(.gukcdb)입니다. FST는 키 길이에 비례해 조회하며 용량이 작아 격자 분절에 권장되고, CDB는 상수 시간 조회와 단순한 구조가 장점입니다. 여러 사전을 명령줄에 반복 지정할 수 있고, 사용자 사전을 먼저 조회한 뒤 번들 사전을 확인하므로 특정 분야의 표기를 안정적으로 우선 적용할 수 있습니다. 동음이의어는 원 한자를 유지하도록 지정하고, 필요한 항목에는 한글 독음을 강제하는 메타데이터도 둘 수 있습니다.
HTML을 깨뜨리지 않는 문서 처리
텍스트 노드만 변환하면서 코드·스크립트·입력 영역과 지정한 요소는 그대로 보존합니다.
웹 문서에서 정규식으로 한자를 치환하면 태그 속성, 코드 예제, 스크립트까지 손상될 수 있습니다. Gukhanmun은 HTML을 파싱해 텍스트 노드와 허용된 속성을 변환한 뒤 태그 구조를 유지해 다시 직렬화합니다. code, pre, script, style, textarea와 translate="no" 영역은 기본적으로 건드리지 않습니다.
프로젝트별 예외도 만들 수 있습니다. 특정 CSS 클래스나 속성을 보존 대상으로 반복 지정하면 수식, 외국어 문장, 제품명 블록을 변환에서 제외할 수 있습니다. 루비 렌더링을 선택하면 현대 한글 위에 원 한자를 주석으로 표시하고, 루비 태그를 지원하지 않는 브라우저에서는 괄호 표기로 읽히게 합니다. 출판·교육 콘텐츠처럼 원문과 독음을 함께 제공해야 하는 경우에 실용적입니다.
설치와 실제 사용 시나리오
CLI는 런타임 의존성이 없는 단일 바이너리로 배포됩니다. macOS, Linux, Windows용 사전 빌드 파일을 받을 수 있고 mise, Windows Package Manager, Cargo 설치도 지원합니다. 변환 엔진을 서비스에 내장하려면 Rust 또는 JavaScript 라이브러리를 이용할 수 있습니다.
먼저 소량의 대표 문서로 기본 프리셋 결과를 확인하고, 잘못 읽히는 고유명사와 전문 용어를 사용자 사전에 추가합니다. 이후 HTML 보존 규칙과 동음이의어 범위를 정한 뒤 전체 자료를 일괄 처리하는 편이 안전합니다. 원문을 별도로 보관하고 변환 결과를 검색과 접근성용 파생 데이터로 취급하면 오류가 발견돼도 다시 생성하기 쉽습니다.
- 디지털 아카이브: 근현대 신문과 공문서의 검색 가능한 한글 사본 생성
- 법률과 학술 서비스: 전문 사전을 붙여 일관된 독음으로 전처리
- 웹 출판: HTML 구조와 코드 예제를 보존하면서 본문만 변환
- 교육 콘텐츠: 루비 주석으로 한글 독음과 원 한자를 함께 표시
- NLP 파이프라인: 한자 혼용으로 분산된 검색어와 토큰을 한글 형태로 정규화
대안과 비교
| 접근 | 강점 | 유의점 |
|---|---|---|
| Gukhanmun | 한국어 규칙, 문서 구조, 사용자 사전을 함께 처리 | 희귀 고유명사는 별도 사전 검수가 필요 |
| 단순 문자 매핑 | 구현이 쉽고 매우 빠름 | 문맥, 단어 경계, 두음법칙, 동음이의어 대응이 약함 |
| 범용 형태소 분석기 | 품사와 문장 분석 등 폭넓은 NLP 가능 | 한자 혼용 문서 변환과 HTML 보존은 별도 개발 필요 |
| 상용 번역과 교정 API | 운영 편의성과 부가 언어 기능 | 비용, 개인정보, 재현성 및 맞춤 사전 제약 가능 |
| 수작업 교정 | 중요한 문서에서 가장 세밀한 판단 가능 | 대량 처리 비용과 일관성 문제가 큼 |
Gukhanmun의 경쟁력은 모든 한국어 NLP 문제를 해결하는 데 있지 않습니다. 한자 혼용문을 한글 중심 문서로 바꾸는 좁고 까다로운 문제를 CLI, 라이브러리, 문서 형식 보존까지 하나의 흐름으로 제공한다는 점이 핵심입니다. 형태소 분석이나 번역이 목적이라면 다른 도구가 맞지만, 변환 결과의 재현성과 자동화가 중요하다면 비교 우위가 분명합니다.
장점과 한계
장점
- 대한민국과 북한 표기, 두음법칙, 숫자와 동음이의어를 세밀하게 제어합니다.
- CLI와 Rust 및 JavaScript 라이브러리를 모두 제공해 배치와 제품 내장에 대응합니다.
- HTML과 마크다운 구조를 인식하고 코드 및 스크립트 영역을 보호합니다.
- 분야별 사전을 추가하고 우선순위를 정할 수 있습니다.
- 단일 바이너리와 사전 빌드 파일로 설치 부담이 낮습니다.
한계
- 사전에 없는 희귀 인명과 전문 용어는 원하는 독음이 나오지 않을 수 있습니다.
- 자동 변환 결과는 원문의 역사적 표기나 의도까지 완벽히 설명하지 못하므로 중요한 자료는 사람의 검수가 필요합니다.
- 범용 번역기나 형태소 분석기가 아니므로 현대 한글 문장의 교정과 요약은 별도 도구가 필요합니다.
- 사용자 정의 사전을 제대로 운영하려면 용어 수집, 중복 처리, 버전 관리가 뒤따릅니다.
총평
Gukhanmun은 작지만 문제 정의가 선명한 개발 도구입니다. 한자 혼용문을 단순히 읽을 수 있는 한글로 바꾸는 데서 멈추지 않고, 두음법칙과 숫자, 동음이의어, 전문 사전, HTML 보존까지 실제 문서 처리에 필요한 경계를 꼼꼼히 다룹니다. 특히 공개 아카이브나 연구 데이터처럼 같은 규칙으로 반복 변환해야 하는 프로젝트에서 수작업과 단순 치환 사이의 빈틈을 잘 메웁니다.
다만 자동 결과를 원문 자체로 대체하기보다는 검색, 접근성, 분석을 위한 파생본으로 사용하는 것이 좋습니다. 먼저 샘플을 검수하고 분야별 사전을 쌓는 방식으로 도입하면 가치가 커집니다. 서비스 개요와 이미지, 공식 출처는 newflix의 Gukhanmun 페이지에서 한눈에 확인할 수 있습니다.