Hangul Romanize

Common errors

• ModuleNotFoundError: No module named 'hangul_romanize'

  cause The 'hangul-romanize' package has not been installed in the current Python environment.
  fix Run `pip install hangul-romanize` to install the library.

• AttributeError: module 'hangul_romanize' has no attribute 'romanize'

  cause Attempting to call a global `romanize` function directly from the `hangul_romanize` module, which does not exist. The library's API requires instantiation of the `Transliter` class.
  fix You must first import and instantiate the `Transliter` class, then call its `translit` method: `from hangul_romanize import Transliter; from hangul_romanize.rule import academic; transliter = Transliter(academic); romanized = transliter.translit('안녕하세요')`.

• Unexpected Romanization output for a common word or name (e.g., '김치' not romanizing as expected)

  cause The library uses a specific academic rule set, which might not align with other common romanization systems (like Revised Romanization or older informal spellings) or perceived 'correct' pronunciations based on non-standard rules.
  fix Review the `hangul-romanize` GitHub repository and documentation to understand the precise academic rules it implements. If a different romanization standard is desired, consider using an alternative library or implementing custom mapping rules.

Warnings

• gotcha The library primarily implements the 'academic notation rules' (국립국어원 학술 표기법), which may yield different results compared to the more commonly encountered 'Revised Romanization of Korean' (RR) used for public signage, names, and general communication. Users expecting RR may find the output inconsistent with their expectations.
  Fix: Consult the official documentation for the specific academic rules implemented by the library to understand its behavior. If 'Revised Romanization' is strictly required, consider alternative libraries or custom post-processing.
• gotcha Korean romanization, regardless of the system, often struggles to perfectly represent all phonetic nuances due to inherent differences in the phonological systems of Korean and Latin alphabets (e.g., distinctions between aspirated/unaspirated consonants, certain vowels).
  Fix: Understand that romanization is an approximation. For precise pronunciation, direct study of Hangul and Korean phonology is recommended. Do not rely solely on romanization for learning correct pronunciation.
• deprecated The library's last release was on April 7, 2020. While not explicitly deprecated, the infrequent updates suggest it may not actively incorporate new linguistic research, updated academic standards, or significant Python version compatibility fixes that could arise in the future.
  Fix: Verify compatibility with your current Python environment and review GitHub issues for any unaddressed bugs or feature requests. For long-term projects, consider the maintenance status.

Install

• pip install hangul-romanize Install with pip

Imports

• Transliter
  wrong:

  import hangul_romanize

  correct:

  from hangul_romanize import Transliter

  The library exposes its core functionality through the `Transliter` class, not a top-level `romanize` function.
• academic
  wrong:

  from hangul_romanize import academic

  correct:

  from hangul_romanize.rule import academic

  The rule sets are located in the `rule` submodule.

Quickstart

This quickstart demonstrates how to import the `Transliter` class and the `academic` rule set, then use them to romanize Korean Hangul strings. It prints the original and romanized text.

from hangul_romanize import Transliter
from hangul_romanize.rule import academic

# Initialize the transliterator with the academic rule set
transliter = Transliter(academic)

# Romanize a Hangul string
hangul_text = u'안녕하세요'
romanized_text = transliter.translit(hangul_text)
print(f"Original: {hangul_text}, Romanized: {romanized_text}")

# Example with another string
hangul_text_2 = u'한글 로마자 변환'
romanized_text_2 = transliter.translit(hangul_text_2)
print(f"Original: {hangul_text_2}, Romanized: {romanized_text_2}")