@gmana/km-translit

中文文档
0.1.2发布于 2026/10/16MITTypeScriptESM + CJS零依赖近 30 天下载 3442

Khmer to Latin transliteration

原始使用文档
文档目录14 节
  1. Features
  2. Installation
  3. Usage
  4. Khmer to Latin
  5. Latin to Khmer
  6. API
  7. khmerToLatin(text: string, overrides?: Record<string, strin…
  8. latinToKhmer(text: string, overrides?: Record<string, strin…
  9. DEFAULT_OVERRIDES: Record<string, string>
  10. capitalize(text: string): string
  11. How romanization works
  12. Limits
  13. Breaking changes in 0.1.0
  14. License

@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:

RuleExample
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, not Sak) 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:

Input0.0.x0.1.0
អានអាnAn
ភ្នំពេញPhnmpenhPhnom Penh
ព្រះPrhPreah
សៀមរាបSiemarabSiem Reap
ចន្ទChantChan
សុខា!SokhaSokha!
សុន​ស្រេង (ZWSP)SonasrengSon Sreng
latinToKhmer("arun")ារុនអារុន

Also changed:

  • The second-series consonant table was incomplete (ង ញ ន ម យ រ ល វ were missing), which affected vowels after those consonants: សិរី is now Seri (was Serei) and បុរី is now Bori (was Borei).
  • Non-Khmer text is no longer re-cased. khmerToLatin capitalizes only the words it generates.
  • Whitespace is preserved rather than normalized; runs of spaces, tabs and newlines survive.
  • latinToKhmer inserts the អ carrier for vowel-initial syllables, so its output is always valid Khmer.

License

MIT

版本与发布记录

@gmana/km-translit 共发布 3 个版本,首次发布于 2026/04/09;过去 12 个月发布了 3 个版本。

版本发布日期距今
0.1.2latest2026/10/161 个月前
0.0.22026/04/097 个月前
0.0.12026/04/097 个月前

关于 @gmana/km-translit 的常见问题

@gmana/km-translit 是什么?

Khmer to Latin transliteration

如何安装 @gmana/km-translit?

在项目目录运行 npm install @gmana/km-translit,或使用 pnpm add / yarn add / bun add。

@gmana/km-translit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gmana/km-translit 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gmana/km-translit 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gmana/km-translit 可以商用吗?

@gmana/km-translit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gmana/km-translit 的下载量有多少?

根据 npm 官方下载统计,@gmana/km-translit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,442 次,日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gmana/km-translit 还在维护吗?

最新版本 0.1.2 发布于 2026/10/16(1 个月前);至今共发布 3 个版本,其中过去 12 个月发布了 3 个;首次发布于 2026/04/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。