korean-romanizer

korean-romanizer is a python module that romanizes Korean text in Hangul into its alphabet equivalent.

It currently follows the Revised Romanization of Korean rule developed by the National Institute of Korean Language, the official romanization system being used in the Republic of Korea.

Usage

Installation

pip install korean_romanizer

Basic Usage

from korean_romanizer import romanize

romanize("안녕하세요")
# returns "annyeonghaseyo"

The existing class API remains supported for compatibility:

from korean_romanizer import Romanizer

Romanizer("안녕하세요").romanize()
# returns "annyeonghaseyo"

The formerly documented module import path also remains supported:

from korean_romanizer.romanizer import Romanizer

Use the kroman command for shell workflows:

kroman 안녕하세요
# annyeonghaseyo

Check the installed command version:

kroman --version
# kroman <installed-version>

Wildcard imports now follow the explicit public API in __all__:

from korean_romanizer import *

This imports only romanize, Romanizer, Pronouncer, and Syllable.

Pronouncer and Syllable are also exported as lower-level compatibility APIs. Constants, tables, and helper functions are internal implementation details and should not be imported by application code.

Development

Install the local development tools with the dev extra:

python3 -m pip install -e ".[dev]"

Useful checks:

python3 -m pytest
python3 -m pytest --cov=korean_romanizer
ruff check .
mypy korean_romanizer
python3 -m build

Releasing

Publishing to PyPI is automated using GitHub Actions. Publishing a GitHub release triggers the workflow in .github/workflows/python-publish.yml which builds and uploads the package using the PYPI_API_TOKEN secret. The package version is derived from git tags using setuptools_scm, so create the version tag before publishing the GitHub release.