thairom 0.1.6

Accurate Thai and Lao/Isan romanization for real-world text -- song lyrics, colloquial speech, and dialects.

thairom

Accurate Thai and Lao/Isan romanization for real-world text -- song lyrics, colloquial speech, and dialects.

Installation

pip install thairom

Quick Start

from thairom import romanize

# Thai
print(romanize('สวัสดีครับ'))       # sawatdee krap
print(romanize('ขอบคุณมาก'))       # khop khun mak
print(romanize('หัวใจ'))           # hua jai

# Lao/Isan
print(romanize('ฮักเจ้าหลาย', lang='lo'))  # hak jao laai
print(romanize('ม่วนคัก', lang='lo'))       # muan khak

Features

• Thai romanization using pythainlp's royin engine with word-level corrections
• Lao/Isan dialect support for Thai-script Isan text with proper pronunciation rules (r-to-l substitution, etc.)
• Word correction maps that fix common pythainlp errors on colloquial vocabulary, song lyrics, and everyday phrases
• Handles real-world text -- tested against song lyrics, spoken Thai, and Isan dialect ground truth data
• Clean output -- strips leaked Thai/Lao characters and normalizes whitespace

Why thairom instead of pythainlp alone?

pythainlp's royin romanization engine is solid for formal Thai, but it struggles with colloquial speech, song lyrics, and regional dialects. thairom builds on pythainlp and fixes these gaps:

Thai Text	pythainlp (royin)	thairom	Correct
หัวใจ	hua chai	hua jai	hua jai
น้ำตา	nam ta	nam dta	nam dta
เข้าใจ	khao chai	khao jai	khao jai
ก็	ko	kaw	kaw
เวลา	wela	welaa	welaa
ตลอดเวลา	talot wela	talod welaa	talod welaa
ขอบคุณ	khop khun	khop khun	khop khun
ฮักเจ้าหลาย	(no Isan support)	hak jao laai	hak jao laai

thairom also handles Isan/Lao dialect written in Thai script, which pythainlp does not support at all.

API Reference

romanize(text, lang='th')

Top-level convenience function. Dispatches to romanize_thai or romanize_lao based on lang.

Parameters:

• text (str): Text to romanize.
• lang (str): 'th' for Thai (default), 'lo' for Lao/Isan.

Returns: Lowercase romanized string.

romanize_thai(text)

Romanize Thai text using pythainlp with word-level corrections from THAI_WORD_MAP.

Parameters:

• text (str): Thai text to romanize.

Returns: Lowercase romanized string.

romanize_lao(text)

Romanize Isan/Lao text written in Thai script. Applies Lao pronunciation rules (e.g., initial r becomes l) and word corrections from LAO_WORD_MAP.

Parameters:

• text (str): Isan/Lao text in Thai script.

Returns: Lowercase romanized string.

Word Maps

The correction maps are available as importable dictionaries for inspection or extension:

from thairom.maps import THAI_WORD_MAP, LAO_WORD_MAP

Contributing

Contributions are welcome, especially additions to the word correction maps. The maps were developed using an autoresearch pipeline that scores romanization output against ground truth data. If you find a word that romanizes incorrectly:

1. Add the word and its correct romanization to THAI_WORD_MAP or LAO_WORD_MAP in src/thairom/maps.py.
2. Add a test case to tests/test_romanize.py.
3. Run pytest to verify.
4. Submit a pull request.

Auditing a flashcard catalog

Install the optional reviewer and run a small calibration batch first:

pip install -e ".[review]"
thairom-review review cards.json review-results.jsonl --limit 100
thairom-review summarize review-results.jsonl review-summary

Only change results at or above 0.95 confidence enter review-summary/changes.json. Ambiguous spelling, names, dialect, and lower confidence decisions go to review-summary/uncertain.json for human review. Nothing updates thairom maps or flashcard data automatically; accepted patterns must become map entries plus regression tests before release.

For the full catalog, generate a resumable OpenAI Batch API file (50% lower API cost than synchronous review):

thairom-review batch cards.json thairom-review-batch.jsonl

After downloading the completed batch output, flatten and classify it:

thairom-review import-batch thairom-review-batch.jsonl batch-output.jsonl reviews.jsonl
thairom-review summarize reviews.jsonl review-summary

License

MIT