Korean Romanizer

한글을 로마자로 변환하는 TypeScript 라이브러리입니다. 국립국어원 로마자 표기법을 기반으로 구현되었으며, 많은 부분을 커버할 수 있지만 한글의 특성상 단어 사전 데이터가 없으면 100% 구현하기 어려워 완벽하지는 않습니다.

이 라이브러리는 crizin/korean-romanizer 자바 라이브러리를 TypeScript로 포팅한 버전입니다. 원본 자바 버전과 동일한 기능을 제공하지만, 현대적인 JavaScript/TypeScript 환경에 맞게 최적화되었습니다.

특징

• ✨ 경량화된 번들 (약 15KB)
• 🚀 Tree-shaking 지원
• 📦 ESM과 CommonJS 모듈 모두 지원
• 🔄 국립국어원 로마자 표기법 준수
• 💡 모듈, 네임스페이스, 함수 레벨 임포트 모두 지원

설치

npm install @daun_jung/korean-romanizer

사용 방법

함수 직접 임포트 (권장)

// 개별 함수 직접 임포트 - 가장 간결하고 우아한 방식
import {
  romanize,
  romanizeWithType,
  romanizeWithAssimilation,
} from "@daun_jung/korean-romanizer";
import { Type, ConsonantAssimilation } from "@daun_jung/korean-romanizer";

// 기본 변환
console.log(romanize("안녕하세요")); // "Annyeonghaseyo"

// 자음 동화 옵션 사용
console.log(
  romanizeWithAssimilation("한라산", ConsonantAssimilation.Progressive)
); // "Hallasan"

// 단어 유형 옵션 사용
console.log(romanizeWithType("김철수", Type.Name)); // "Kim Cheolsu"

특정 함수만 임포트

각 함수를 별도의 경로에서 가져올 수도 있습니다. 이 방식은 트리쉐이킹과 번들 사이즈 최적화에 도움이 됩니다.

// 특정 함수만 필요할 경우
import romanize from "@daun_jung/korean-romanizer/romanize";
import romanizeWithType from "@daun_jung/korean-romanizer/romanizeWithType";
import romanizeWithAssimilation from "@daun_jung/korean-romanizer/romanizeWithAssimilation";

// 타입 임포트
import { Type, ConsonantAssimilation } from "@daun_jung/korean-romanizer";

네임스페이스 사용 (기존 방식)

// 네임스페이스 방식 (하위 호환성 유지)
import { KoreanRomanizer } from "@daun_jung/korean-romanizer";
import { Type, ConsonantAssimilation } from "@daun_jung/korean-romanizer";

// 기본 변환
console.log(KoreanRomanizer.romanize("안녕하세요")); // "Annyeonghaseyo"

// 자음 동화 옵션 사용
console.log(
  KoreanRomanizer.romanizeWithAssimilation(
    "한라산",
    ConsonantAssimilation.Progressive
  )
); // "Hallasan"

// 단어 유형 옵션 사용
console.log(KoreanRomanizer.romanizeWithType("김철수", Type.Name)); // "Kim Cheolsu"

옵션

자음 동화 (ConsonantAssimilation)

• Progressive: 순행동화
• Regressive: 역행동화 (기본값)

단어 유형 (Type)

• Substantives: 명사와 같은 실체언
• Compound: 복합어
• District: 주소, 위치
• Name: 사람의 이름
• NameTypical: 가장 일반적으로 사용되는 표기법을 따르는 사람의 이름
• Typical: 일반 단어 (기본값)

개발

빌드

npm run build

테스트

npm test

원본 프로젝트

이 라이브러리는 @crizin이 개발한 korean-romanizer 자바 라이브러리를 기반으로 합니다. 훌륭한 원본 라이브러리를 제공해 주신 crizin님께 감사드립니다.

라이선스

MIT License