thai-rtgs 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-10-06
+
+First release.
+
+- `romanize`, `romanizeName`, `analyze`, `syllabify` and `createRomanizer` for Thai → RTGS (Royal Institute, 1999)
+- Rule-based syllable parser: clusters, leading ห/อ, อักษรนำ, ร หัน, karan, silent ร and final vowels, inferred a/o vowels, ฤ/ฦ
+- Pali/Sanskrit combining forms for names and compounds (ธนกฤต thanakrit, ภัทรกมล phattharakamon)
+- Built-in dictionary: 77 provinces, 50 Bangkok districts, irregular words, common given names and name parts; user and per-call dictionaries
+- Word segmentation with `Intl.Segmenter`, with dictionary-only and custom segmenter options
+- Options for letter case, word and syllable separators, ambiguity hyphens, Thai digits, ๆ and ฯ
+- ESM + CommonJS builds with TypeScript types; no runtime dependencies

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PhaiKub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# thai-rtgs — ถอดอักษรไทยเป็นอักษรโรมันแบบ RTGS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ระบบถอดอักษรไทยเป็นอักษรโรมันตาม **Royal Thai General System of Transcription (RTGS)** หรือหลักเกณฑ์การถอดอักษรไทยเป็นอักษรโรมันแบบถ่ายเสียงของราชบัณฑิตยสถาน (พ.ศ. 2542) เป็น library ภาษา TypeScript ไม่มี dependency ใช้ได้ทั้ง Node และเบราว์เซอร์ (ESM + CJS + type definitions)
+
+```ts
+import { romanize } from 'thai-rtgs';
+
+romanize('กรุงเทพมหานคร', { case: 'title' });   // 'Krung Thep Maha Nakhon'
+romanize('สวัสดีครับ ยินดีต้อนรับสู่ประเทศไทย'); // 'sawatdi khrap yindi tonrap su prathet thai'
+romanize('ถนน', { syllableSeparator: '-' });      // 'tha-non'
+```
+
+## ทำงานอย่างไร
+
+1. **Normalize** — แก้รูปแบบการพิมพ์ที่ต่างกัน (`ํา`→`ำ`, `เเ`→`แ`, วรรณยุกต์ที่พิมพ์ก่อนสระ, อักขระที่มองไม่เห็น)
+2. **Tokenize** — แยกข้อความไทย อังกฤษ ตัวเลข เครื่องหมาย `ๆ` `ฯ` และ `ฯลฯ`
+3. **ตัดคำ** — ใช้ `Intl.Segmenter('th')` แล้วรวม segment ที่ต่อกันเป็นคำในพจนานุกรม (เช่น กรุงเทพมหานคร)
+4. **พจนานุกรม** — มีชื่อ 77 จังหวัด, 50 เขตของกรุงเทพฯ, คำที่อ่านไม่ตรงกฎ (ราชการ, ผลไม้, ประวัติศาสตร์, ก็, …) และชื่อคน/ส่วนประกอบของนามสกุล (สกุล, ตระกูล, สวัสดิ์, …) คำในพจนานุกรมในตัวยังถูกจับคู่ภายในคำที่ยาวกว่าได้ด้วย (มี|สวัสดิ์ → misawat) ผู้ใช้เพิ่มหรือแก้คำเองได้
+5. **แยกพยางค์ตามกฎ** — สำหรับคำที่ไม่มีในพจนานุกรม หาวิธีแบ่งพยางค์ที่ "ต้นทุนต่ำสุด" (dynamic programming) จาก template ของสระ พยัญชนะต้น ควบกล้ำ ห นำ ตัวสะกด การันต์ และ ร หัน สระที่ไม่ได้เขียนรูป (ถนน → tha-non) มีต้นทุน จึงถูกเลือกเฉพาะเมื่อตัวสะกดบังคับให้ต้องมี นอกจากนี้ยังรู้จัก **combining forms** ของคำบาลี-สันสกฤตที่อ่านมีพยางค์เชื่อมเมื่อมีส่วนอื่นตามมา (ธน|กฤต → thanakrit, ภัทร|กมล → phattharakamon) และอักษรนำที่เขียนสระหน้าไว้ก่อน (เจริญ → charoen, เสนอ → sanoe)
+6. **จัดรูปแบบ** — ต่อพยางค์และคำ ใส่ยัติภังค์ (`-`) เมื่ออ่านกำกวม (สะอาด → sa-at) และจัดตัวพิมพ์เล็ก/ใหญ่
+
+รายละเอียดกฎทั้งหมดอยู่ใน [docs/rtgs-rules.md](docs/rtgs-rules.md)
+
+## ความแม่นยำ
+
+`npm run eval` วัดผลกับชุดทดสอบใน [test/fixtures/golden.ts](test/fixtures/golden.ts):
+
+| ชุดทดสอบ | ผล |
+|---|---|
+| คำทั่วไป อ่านด้วยกฎล้วน (ปิดพจนานุกรม) | 225/225 |
+| คำศัพท์ประจำวันที่ไม่ได้ใช้ระหว่างปรับกฎ (เปิดพจนานุกรม) | 190/190 |
+| ชื่อจริงคนไทย (ชื่อจริงอย่างเดียว ไม่รวมนามสกุล) | 124/124 |
+| คำที่ต้องใช้พจนานุกรม | 25/25 |
+| จังหวัด (Title case) | 28/28 |
+| ประโยค | 8/8 |
+
+ตัวเลขนี้วัดกับคำที่ใช้ปรับกฎเอง จึงสูงกว่าความแม่นยำจริง ตัวเลขที่บอกความแม่นยำจริงได้ดีกว่าคือผลก่อนปรับ: ชุดคำศัพท์ประจำวันได้ 184/190 (96.8%) และชุดชื่อจริงได้ 106/124 (85%) คำที่ผิดเกือบทั้งหมดเป็นคำบาลี-สันสกฤตที่มีพยางค์เชื่อม (เอกสาร ek-ka-san, ธนกฤต tha-na-krit) ซึ่งกฎอย่างเดียวคาดไม่ได้
+
+ทดลองเพิ่มเติมกับรายชื่อจริงของนักเรียนราว 1,900 ชื่อและ 2,400 นามสกุล (ข้อมูลไม่ได้เก็บไว้ใน repo) สุ่มตรวจ 120 รายการที่ไม่ได้ใช้ปรับกฎ ได้ชื่อจริงถูกประมาณ 80% และนามสกุลถูกประมาณ 93% จากนั้นแก้กฎและเพิ่มส่วนประกอบชื่อที่พบบ่อยเข้าไปแล้ว ชื่อและนามสกุลที่ไม่มีในชุดทดสอบอาจยังผิดได้ ให้ตรวจผลที่มี `confidence: "medium"` และเพิ่มคำผ่าน `dictionary`
+
+## Library
+
+```bash
+npm install thai-rtgs
+```
+
+```ts
+import { romanize, romanizeName, analyze, syllabify, createRomanizer } from 'thai-rtgs';
+
+// ตัวเลือก
+romanize('สะอาด');                                   // 'sa-at'
+romanize('สะอาด', { hyphenateAmbiguous: false });    // 'saat'
+romanize('เด็กๆ เล่นกัน', { case: 'sentence' });     // 'Dek dek len kan'
+romanize('วันที่ ๑๒ มกราคม ๒๕๖๗');                    // 'wan thi 12 mokkarakhom 2567'
+romanize('ฉันชอบ iPhone 15', { keepNonThai: false }); // 'chan chop'
+
+// ชื่อคน: อ่านแต่ละส่วนที่คั่นด้วยเว้นวรรคเป็นหนึ่งคำ แยกคำนำหน้าออก และขึ้นต้นตัวใหญ่
+romanizeName('นางสาวภัทรกมล สุขสวัสดิ์'); // 'Nangsao Phattharakamon Suksawat'
+
+// คำเฉพาะสำหรับการเรียกครั้งเดียว (- คั่นพยางค์ เว้นวรรคคั่นคำ)
+romanize('สมชาย ใจดี', { case: 'title', dictionary: { สมชาย: 'som-chai', ใจดี: 'chai-di' } }); // 'Somchai Chaidi'
+
+// instance ที่มีพจนานุกรมและค่าตั้งต้นของตัวเอง
+const rtgs = createRomanizer({ case: 'title' });
+rtgs.addWord('ภัทรา', 'phat-tha-ra');
+rtgs.romanize('ภัทรา');   // 'Phatthara'
+rtgs.removeWord('ราชบุรี'); // ซ่อนคำในพจนานุกรมในตัว (เฉพาะ instance นี้)
+
+// รายละเอียดทีละคำ/พยางค์
+analyze('ถนนราชบุรี').tokens[0].words;
+// [{ thai: 'ถนน', roman: 'thanon', source: 'rules', confidence: 'medium', syllables: [...] },
+//  { thai: 'ราชบุรี', roman: 'ratchaburi', source: 'dictionary', confidence: 'dictionary', ... }]
+
+syllabify('เปลี่ยน');
+// [{ thai: 'เปลี่ยน', roman: 'plian', initial: { thai: 'ปล', roman: 'pl' },
+//    vowel: { thai: 'เ-ีย', roman: 'ia', implicit: false }, final: { thai: 'น', roman: 'n' },
+//    silent: '', rules: ['true-cluster'] }]
+```
+
+### ตัวเลือก (`RomanizeOptions`)
+
+| ตัวเลือก | ค่า | ค่าเริ่มต้น | ความหมาย |
+|---|---|---|---|
+| `case` | `lower` `upper` `title` `sentence` | `lower` | ตัวพิมพ์ `title` ขึ้นต้นตัวใหญ่ทุกคำ เหมาะกับชื่อเฉพาะ |
+| `wordSeparator` | string | `' '` | ตัวคั่นระหว่างคำไทย |
+| `syllableSeparator` | string | `''` | ตัวคั่นพยางค์ เช่น `'-'` |
+| `hyphenateAmbiguous` | boolean | `true` | ใส่ `-` เมื่อพยางค์ต่อกันแล้วอ่านกำกวม (sa-at, sa-nga) |
+| `thaiDigits` | `arabic` `keep` | `arabic` | เลขไทย ๐-๙ |
+| `maiYamok` | `repeat` `keep` `drop` | `repeat` | ไม้ยมก `ๆ` |
+| `paiyannoi` | `drop` `keep` | `drop` | ไปยาลน้อย `ฯ` (`ฯลฯ` → `etc.`) |
+| `keepNonThai` | boolean | `true` | เก็บข้อความภาษาอื่น ตัวเลข และเครื่องหมาย |
+| `useBuiltinDictionary` | boolean | `true` | ใช้พจนานุกรมในตัว |
+| `dictionary` | `Record<string, string>` | — | คำเพิ่มเติมสำหรับการเรียกครั้งนั้น |
+| `segmenter` | `intl` `dictionary` `none` หรือ function | `intl` | วิธีตัดคำ (ถ้าไม่มี `Intl.Segmenter` จะใช้ `dictionary`) |
+
+ค่า `confidence` ของแต่ละคำ: `dictionary` (จากพจนานุกรม), `high` (สระเขียนรูปครบ), `medium` (มีสระที่ไม่เขียนรูป ควรตรวจถ้าเป็นชื่อเฉพาะ), `low` (มีอักษรที่แยกพยางค์ไม่ได้ และมี warning `unparsed`)
+
+## พัฒนา
+
+```bash
+npm install
+npm test            # vitest
+npm run typecheck
+npm run eval        # รายงานความแม่นยำ
+npm run build       # dist/ (ESM + CJS + .d.ts)
+```
+
+รองรับ Node.js 18 ขึ้นไป (การพัฒนาใช้ Node 20 ขึ้นไป)
+
+## ข้อจำกัด
+
+- RTGS ไม่มีวรรณยุกต์และความยาวสระ จึงแปลงกลับเป็นอักษรไทยไม่ได้
+- คำบาลี-สันสกฤตที่มีพยางค์เชื่อม (ราชบุรี rat-cha-bu-ri, ผลไม้ phon-la-mai) ชื่อคน และคำทับศัพท์ ต้องพึ่งพจนานุกรม คำที่กฎอ่านผิดให้เพิ่มผ่าน `dictionary` หรือ `addWord`
+- ชื่อคนที่อยู่ในประโยคอาจถูกตัดเป็นหลายคำ (`Intl.Segmenter` ไม่รู้จักชื่อ) ให้ใช้ `romanizeName()` กับชื่อ ซึ่งอ่านแต่ละส่วนเป็นหนึ่งคำ
+- ผลการตัดคำของ `Intl.Segmenter` ขึ้นกับเวอร์ชัน ICU ของ runtime อาจต่างกันเล็กน้อย คำประสมที่ ICU ไม่แยก (เช่น รถไฟฟ้า) จะออกมาติดกัน (`rotfaifa`)
+- ชื่อจังหวัดและเขตเขียนตามแบบราชบัณฑิตยสถาน (เช่น Chon Buri, Buri Ram) ซึ่งอาจต่างจากตัวสะกดที่ใช้กันทั่วไป (Chonburi, Buriram) แก้ได้ผ่าน `dictionary`
+
+---
+
+## English quickstart
+
+`thai-rtgs` converts Thai script to Latin letters with the Royal Thai General System of Transcription. Words not in its dictionary go through a rule-based syllable parser, which finds the lowest-cost segmentation of Thai orthographic syllables. A dictionary covers the provinces, the Bangkok districts and words with irregular or Pali/Sanskrit readings. It has no dependencies and runs in Node and browsers.
+
+```ts
+import { romanize } from 'thai-rtgs';
+romanize('เชียงใหม่', { case: 'title' }); // 'Chiang Mai'
+```