@gmana/km-translit
A lightweight, dependency-free library for transliterating Khmer text to Latin script (romanization) and back.
Romanization follows the BGN/PCGN 1972 system for Khmer, restricted to plain ASCII — the diacritics that system
uses (â, ŏ, ĕə, é) are dropped so the output is usable in names, identifiers and URLs. It is therefore a
BGN/PCGN-derived profile, not a conformant implementation.
Features
- Khmer to Latin (
khmerToLatin) — syllable-aware romanization with proper coda forms. - Latin to Khmer (
latinToKhmer) — best-effort inverse that always emits well-formed Khmer. - Overrides — a dictionary for names and toponyms that the rules cannot derive.
- Dependency-free — small bundle, ESM and CJS.
- TypeScript — fully typed out of the box.
Installation
npm install @gmana/km-translit
pnpm add @gmana/km-translit
Usage
Khmer to Latin
import { khmerToLatin } from "@gmana/km-translit"
khmerToLatin("សុន ស្រេង") // "Son Sreng"
khmerToLatin("ចាន់ សុភា") // "Chan Sophea"
khmerToLatin("ហ៊ុន សែន") // "Hun Sen"
khmerToLatin("ភ្នំពេញ") // "Phnom Penh"
Text outside the Khmer block is preserved exactly as written — Latin, punctuation, Khmer digits and whitespace all pass through untouched:
khmerToLatin("Hello សុខា!") // "Hello Sokha!"
khmerToLatin("Khmer ១២៣ Text") // "Khmer ១២៣ Text"
Word boundaries come from spaces and from ZWSP (U+200B), the conventional Khmer word separator:
khmerToLatin("សុនស្រេង") // "Son Sreng" (separated by U+200B)
Custom overrides take precedence over both the rules and the built-in defaults:
khmerToLatin("សុន ស្រេង", { សុន: "sun", ស្រេង: "sraeng" }) // "Sun Sraeng"
Latin to Khmer
import { latinToKhmer } from "@gmana/km-translit"
latinToKhmer("son seng") // "សុន សេង"
latinToKhmer("rath") // "រតន៍" (built-in override)
latinToKhmer("rath", { rath: "រ័ត្ន" }) // "រ័ត្ន"
API
khmerToLatin(text: string, overrides?: Record<string, string>): string
Romanizes Khmer text. Each Khmer word is capitalized; surrounding text is left alone. overrides maps a Khmer word to
its Latin form and is layered over DEFAULT_OVERRIDES.
latinToKhmer(text: string, overrides?: Record<string, string>): string
Converts Latin text back to Khmer. Romanization discards information — series, vowel length, and the choice among
consonants that share a sound — so this is lossy: the output is always well-formed Khmer, but it will not always
match the original spelling. Use overrides for names that must round-trip exactly.
DEFAULT_OVERRIDES: Record<string, string>
Built-in exceptions. Khmer runs have no internal word boundaries, so multi-word proper nouns written without a
separator (ភ្នំពេញ → Phnom Penh) live here.
capitalize(text: string): string
Capitalizes the first letter of each space-separated word and lower-cases the rest.
How romanization works
Khmer text is parsed into syllables — onset cluster, vowel, coda — rather than character by character. That structure is what makes the following correct:
| Rule | Example |
|---|---|
| Codas use unreleased finals, not onset forms | ចន្ទ → Chan (not Chant) |
| Sonorant subscripts keep the base's series | ស្រេង → Sreng, ស្ទឹង → Stoeng |
ំ and ះ fuse with the vowel | ព្រះ → Preah, ភ្នំ → Phnum |
៊ / ៉ shift the series | សុន → Son, ស៊ុន → Sun |
់ marks a coda | កង់ → Kang |
៍ / ៑ silence their consonant | តន៍ → Ta |
ៗ repeats the previous word | ខ្ញុំៗ → Khnhum Khnhum |
Limits
- Word segmentation inside a Khmer run is not possible without a dictionary. Separate words with a space or ZWSP,
or add the phrase to
overrides. - Etymological spellings that are not pronounced as written (
ស័ក្តិ→Sakte, notSak) need an override. - Where a name has an established spelling that the rules do not produce (
វណ្ណា→Vonna, conventionally Vanna), use an override.
Breaking changes in 0.1.0
The core was rewritten as a syllable engine, which corrects output that previous versions got wrong:
| Input | 0.0.x | 0.1.0 |
|---|---|---|
អាន | អាn | An |
ភ្នំពេញ | Phnmpenh | Phnom Penh |
ព្រះ | Prh | Preah |
សៀមរាប | Siemarab | Siem Reap |
ចន្ទ | Chant | Chan |
សុខា! | Sokha | Sokha! |
សុនស្រេង (ZWSP) | Sonasreng | Son Sreng |
latinToKhmer("arun") | ារុន | អារុន |
Also changed:
- The second-series consonant table was incomplete (
ង ញ ន ម យ រ ល វwere missing), which affected vowels after those consonants:សិរីis nowSeri(wasSerei) andបុរីis nowBori(wasBorei). - Non-Khmer text is no longer re-cased.
khmerToLatincapitalizes only the words it generates. - Whitespace is preserved rather than normalized; runs of spaces, tabs and newlines survive.
latinToKhmerinserts theអcarrier for vowel-initial syllables, so its output is always valid Khmer.
License
MIT