{"id":9028,"library":"hangul-romanize","title":"Hangul Romanize","description":"hangul-romanize is a Python library for romanizing Hangul strings, specifically adhering to the academic notation rules (국립국어원 학술 표기법) of the National Institute of Korean Language. As of version 0.1.0, it provides tools for converting Korean text into the Latin alphabet based on these scholarly guidelines.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://github.com/youknowone/hangul-romanize","tags":["hangul","romanization","korean","transliteration","linguistics","academic"],"install":[{"cmd":"pip install hangul-romanize","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The library exposes its core functionality through the `Transliter` class, not a top-level `romanize` function.","wrong":"import hangul_romanize","symbol":"Transliter","correct":"from hangul_romanize import Transliter"},{"note":"The rule sets are located in the `rule` submodule.","wrong":"from hangul_romanize import academic","symbol":"academic","correct":"from hangul_romanize.rule import academic"}],"quickstart":{"code":"from hangul_romanize import Transliter\nfrom hangul_romanize.rule import academic\n\n# Initialize the transliterator with the academic rule set\ntransliter = Transliter(academic)\n\n# Romanize a Hangul string\nhangul_text = u'안녕하세요'\nromanized_text = transliter.translit(hangul_text)\nprint(f\"Original: {hangul_text}, Romanized: {romanized_text}\")\n\n# Example with another string\nhangul_text_2 = u'한글 로마자 변환'\nromanized_text_2 = transliter.translit(hangul_text_2)\nprint(f\"Original: {hangul_text_2}, Romanized: {romanized_text_2}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"0.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install hangul-romanize` to install the library.","cause":"The 'hangul-romanize' package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'hangul_romanize'"},{"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('안녕하세요')`.","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.","error":"AttributeError: module 'hangul_romanize' has no attribute 'romanize'"},{"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.","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.","error":"Unexpected Romanization output for a common word or name (e.g., '김치' not romanizing as expected)"}]}