lyric-romanizer 0.2.0 → 0.3.0

package/docs/README.hi.md

@@ -0,0 +1,296 @@
+# lyric-romanizer
+
+[![npm version](https://img.shields.io/npm/v/lyric-romanizer.svg)](https://www.npmjs.com/package/lyric-romanizer)
+[![license](https://img.shields.io/npm/l/lyric-romanizer.svg)](https://github.com/thedavidweng/lyric-romanizer/blob/main/LICENSE)
+
+> **दर्शन: पहिया दोबारा न इजाद करो।**
+> इस परियोजना में जानबूझकर रोमनाइज़ेशन तर्क को शुरू से बनाने से बचा गया है। इसके बजाय, यह प्रत्येक लिपि के लिए समुदाय-अनुरक्षित बेहतरीन लाइब्रेरियों को जोड़ता है — ऑर्केस्ट्रेशन परत पर ध्यान केंद्रित करते हुए: लिपि पहचान, इंजन रूटिंग, बोली प्रसंस्करण, और एकीकृत API। निर्भता सूची में प्रत्येक रोमनाइज़ेशन इंजन डोमेन विशेषज्ञों द्वारा अनुरक्षित, परीक्षित लाइब्रेरी है। यही इस परियोजना का मूल विचार है।
+
+गीतों के लिए लिपि पहचान और स्थानीय रोमनाइज़ेशन इंजन। जापानी, चीनी (मंदारिन और कैंटोनीज़), कोरियाई, सिरिलिक, भारतीय लिपियाँ, तमिल, और थाई सहित 12 लिपियों का समर्थन करता है — सब स्थानीय रूप से, बिना किसी API कॉल के।
+
+[Spotify Karaoke](https://github.com/haroldalan/spotify-karaoke) से निकाला गया। [OpenKara](https://github.com/thedavidweng/openkara) द्वारा उपयोग किया जाता है।
+
+[English](https://github.com/thedavidweng/lyric-romanizer#readme) | [日本語](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ja.md) | [中文（简体）](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.zh-CN.md) | [中文（粵語）](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.zh-yue.md) | [한국어](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ko.md) | [Русский](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ru.md) | [தமிழ்](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ta.md) | [ไทย](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.th.md)
+
+## विशेषताएँ
+
+- **शून्य API कॉल** — सभी रोमनाइज़ेशन स्थानीय रूप से चलता है
+- **स्वचालित लिपि पहचान** — पाठ दें, उपयोग की गई लिपि मिलेगी
+- **12+ लिपियाँ** — जापानी, चीनी, कोरियाई, सिरिलिक, 6 भारतीय लिपियाँ, तमिल, थाई
+- **कैंटोनीज़ समर्थन** — डिफ़ॉल्ट मंदारिन पिनयिन के साथ-साथ कैंटोनीज़ ज्युटपिंग (Jyutping)
+- **हल्का पहचान उपपथ** — रोमनाइज़ेशन इंजन शामिल किए बिना केवल लिपि पहचान (और बाहरी-लिपि वर्गीकरण) आयात करें
+- **आलसी इंजन** — प्रत्येक इंजन पहले उपयोग पर लोड होता है; जब तक आप रोमनाइज़ न करें, मुख्य प्रविष्टि आयात करने की कोई लागत नहीं
+- **प्लग-योग्य इंजन** — किसी भी अंतर्निर्मित इंजन को ओवरराइड करें, या बाहरी रूप से रोमनाइज़ की जाने वाली लिपियों के लिए अपना स्वयं का एडाप्टर प्लग करें
+- **अवलोकनीय फ़ॉलबैक** — प्रति-पंक्ति फ़्लैग बताते हैं कि कब कोई इंजन विफल हुआ और किसी पंक्ति को अंतिम उपाय के रूप में लिप्यंतरित किया गया
+- **यूक्रेनी-सचेत सिरिलिक** — यूक्रेनी विशिष्ट वर्णों की स्वचालित पहचान और सही लिप्यंतरण प्रीसेट लागू करें
+- **सादे Node ESM में चलता है** — किसी बंडलर की आवश्यकता नहीं
+
+## स्थापना
+
+```bash
+npm install lyric-romanizer
+```
+
+```bash
+yarn add lyric-romanizer
+```
+
+```bash
+pnpm add lyric-romanizer
+```
+
+## त्वरित प्रारंभ
+
+```ts
+import { createRomanizer, detectScript } from 'lyric-romanizer';
+
+const romanizer = createRomanizer();
+
+// लिपि स्वचालित पहचान और रोमनाइज़ेशन
+const result = await romanizer.romanizeLines(['你好世界', '很高兴认识你']);
+// { script: 'chinese', lines: ['nǐ hǎo shì jiè', 'hěn gāo xìng rèn shi nǐ'], fallbacks: [false, false] }
+
+// एक पंक्ति का रोमनाइज़ेशन
+const line = await romanizer.romanizeLine('안녕하세요');
+// 'annyeonghaseyo'
+```
+
+> **पहचान की सूक्ष्मता** — `romanizeLines` **सभी पंक्तियों में एक बार** प्रमुख लिपि का पता लगाता है और उसे हर पंक्ति के लिए पिन कर देता है (जानबूझकर: किसी जापानी गीत के भीतर केवल-कांजी वाली पंक्तियों को जापानी इंजन तक पहुँचना ज़रूरी है, और सरणी में कोई भी काना `japanese` को पिन कर देता है)। इसके बजाय `romanizeLine` को लूप में कॉल करने पर **प्रति पंक्ति** पहचान होती है और यह प्रत्येक पंक्ति को अलग इंजन पर रूट कर सकता है। पिन की गई लिपि के अंतर्गत शुद्ध-लैटिन पंक्तियाँ जैसी की वैसी लौटाई जाती हैं। देखें **मिश्रित-लिपि सरणियाँ**।
+
+## API
+
+### आयात
+
+```ts
+// मुख्य प्रविष्टि — पूर्ण रोमनाइज़ेशन इंजन
+import {
+  createRomanizer,
+  detectScript,
+  isLatinScript,
+  requiresExternalRomanization,
+  UnsupportedRomanizationError,
+} from 'lyric-romanizer';
+
+// केवल पहचान उपपथ — हल्का, रोमनाइज़ेशन निर्भता रहित
+import {
+  detectScript,
+  isLatinScript,
+  requiresExternalRomanization,
+  NON_LATIN_SCRIPT_RE,
+} from 'lyric-romanizer/detector';
+```
+
+### प्रकार
+
+```ts
+type ScriptType =
+  | 'japanese' | 'chinese' | 'korean' | 'cyrillic'
+  | 'devanagari' | 'gujarati' | 'gurmukhi' | 'telugu'
+  | 'kannada' | 'odia' | 'tamil' | 'malayalam'
+  | 'bengali' | 'arabic' | 'hebrew' | 'thai'
+  | 'latin' | 'other';
+
+interface Romanizer {
+  romanizeLine(line: string, options?: RomanizeOptions): Promise<string>;
+  romanizeLines(lines: readonly string[], options?: RomanizeOptions): Promise<RomanizeResult>;
+}
+
+// `dialect` केवल 'chinese' के लिए लागू होता है; बाकी हर लिपि इसे अनदेखा करती है।
+type RomanizeOptions = { script?: ScriptType; dialect?: 'mandarin' | 'cantonese' };
+
+// `fallbacks` `lines` के साथ संरेखित है: true वहाँ जहाँ इंजन विफल हुआ और
+// पंक्ति को अंतिम उपाय के रूप में यूनिवर्सल रूप से लिप्यंतरित किया गया।
+type RomanizeResult = { script: ScriptType; lines: string[]; fallbacks?: boolean[] };
+
+// एक इंजन एडाप्टर: अपनी लिपि की एक पंक्ति को रोमनाइज़ करता है। फेंकना (या
+// अस्वीकार करना) यूनिवर्सल लिप्यंतरण फ़ॉलबैक को ट्रिगर करता है।
+type RomanizeEngine = (line: string, context: { dialect: 'mandarin' | 'cantonese' }) => string | Promise<string>;
+
+type RomanizerOptions = {
+  japaneseDictPath?: string;
+  engines?: Partial<Record<ScriptType, RomanizeEngine>>;
+};
+```
+
+### `createRomanizer(options?)`
+
+फ़ैक्टरी जो `Romanizer` इंस्टेंस लौटाता है। प्रत्येक इंजन पहले उपयोग पर आलसी रूप से लोड होता है और कैश होता है — विफल लोड अगली कॉल पर पुनः प्रयास करता है।
+
+```ts
+const romanizer = createRomanizer();
+
+// Kuromoji शब्दकोश CDN पथ ओवरराइड (सेल्फ-होस्टिंग आदि के लिए)
+const romanizer = createRomanizer({
+  japaneseDictPath: 'https://my-cdn.com/kuromoji/dict',
+});
+```
+
+#### इंजन एडाप्टर
+
+`options.engines` किसी लिपि के लिए अंतर्निर्मित इंजन को ओवरराइड करता है — या ऐसी लिपि में इंजन प्लग करता है जिसमें कोई अंतर्निर्मित इंजन नहीं है (`arabic`, `hebrew`, `malayalam`, `bengali`, `other`), ताकि `romanizeLines` हर लिपि को एक ही इंटरफ़ेस के माध्यम से संभाल सके। डिफ़ॉल्ट रूप से लाइब्रेरी **शून्य नेटवर्क I/O** करती है; रिमोट एडाप्टर प्लग करना कॉलर का स्पष्ट निर्णय है।
+
+```ts
+const romanizer = createRomanizer({
+  engines: {
+    // स्थानीय इंजन रहित लिपियों के लिए अपना स्वयं का बाहरी रोमनाइज़ेशन लाएँ।
+    arabic: async (line) => myTransliterationApi(line),
+    // या किसी अंतर्निर्मित इंजन को बदलें (उदा. परीक्षणों में नकली इंजन से)।
+    korean: (line) => myKoreanRomanizer(line),
+  },
+});
+
+await romanizer.romanizeLines(['مرحبا']);
+// { script: 'arabic', lines: [...], fallbacks: [false] } — अब और नहीं फेंकता
+```
+
+बिना किसी इंजन वाली लिपियाँ — अंतर्निर्मित या इंजेक्ट की गई — अब भी `UnsupportedRomanizationError` फेंकती हैं।
+
+### `detectScript(lines)`
+
+दी गई पाठ पंक्तियों में प्रमुख लिपि का पता लगाता है। पहले जापानी काना की जाँच करता है (निर्धारक), फिर अन्य सभी लिपियों को वर्ण गणना से स्कोर करता है।
+
+```ts
+detectScript(['こんにちは']);          // 'japanese'
+detectScript(['你好世界']);            // 'chinese'
+detectScript(['Привет']);             // 'cyrillic'
+detectScript(['Hello world']);        // 'latin'
+detectScript(['123 ???']);            // 'other'
+```
+
+### `isLatinScript(lines)`
+
+त्वरित जाँच — यदि पाठ में केवल लैटिन अक्षर हैं (CJK, सिरिलिक, भारतीय लिपियाँ आदि के बिना) तो `true` लौटाता है। रोमनाइज़ेशन को पूरी तरह छोड़ने के लिए उपयोगी।
+
+```ts
+isLatinScript(['Hello world']);  // true
+isLatinScript(['안녕하세요']);    // false
+isLatinScript(['♪♪♪']);         // false (कोई अक्षर नहीं)
+```
+
+### `requiresExternalRomanization(script)`
+
+उन लिपियों के लिए `true` लौटाता है जिनमें कोई अंतर्निर्मित इंजन नहीं है और जिन्हें बाहरी API की आवश्यकता है। हल्के `lyric-romanizer/detector` उपपथ से आयात करने योग्य, इसलिए "क्या मुझे किसी बाहरी सेवा की ओर शाखा बनानी चाहिए?" का उत्तर देने में शून्य इंजन पेलोड लगता है।
+
+```ts
+requiresExternalRomanization('chinese');   // false
+requiresExternalRomanization('arabic');    // true
+requiresExternalRomanization('malayalam'); // true
+```
+
+### `romanizer.romanizeLine(line, options?)`
+
+एक पंक्ति का रोमनाइज़ेशन करता है। यदि `script` छोड़ दिया जाए, तो `detectScript` के माध्यम से **प्रति पंक्ति** स्वचालित रूप से पहचाना जाता है — `romanizeLine` पर लूप करने से प्रत्येक पंक्ति अलग इंजन पर रूट हो सकती है, `romanizeLines` के विपरीत, जो पूरी सरणी के लिए एक ही लिपि पिन करता है। लैटिन पाठ या बिना अक्षर वाली सामग्री के लिए मूल पंक्ति जैसी की वैसी लौटाता है।
+
+चीनी पाठ के लिए `dialect` विकल्प रोमनाइज़ेशन प्रणाली को नियंत्रित करता है: `'mandarin'` (डिफ़ॉल्ट) पिनयिन का उपयोग करता है, `'cantonese'` [Jyutping](https://github.com/CanCLID/to-jyutping) का उपयोग करता है। अन्य लिपियाँ `dialect` को अनदेखा करती हैं।
+
+बिना किसी इंजन (अंतर्निर्मित या इंजेक्ट की गई) वाली लिपियों के लिए `UnsupportedRomanizationError` **फेंकता है**।
+
+```ts
+await romanizer.romanizeLine('你好世界');
+// 'nǐ hǎo shì jiè' (डिफ़ॉल्ट: मंदारिन/पिनयिन)
+
+await romanizer.romanizeLine('你好', { dialect: 'cantonese' });
+// 'nei5 hou2' (Jyutping)
+
+await romanizer.romanizeLine('Привет мир');
+// 'Privet mir'
+
+await romanizer.romanizeLine('Hello world');
+// 'Hello world' (जैसी की वैसी)
+
+await romanizer.romanizeLine('مرحبا');
+// throws UnsupportedRomanizationError { script: 'arabic' }
+```
+
+### `romanizer.romanizeLines(lines, options?)`
+
+कई पंक्तियों का समानांतर में रोमनाइज़ेशन करता है। **सभी पंक्तियों में एक बार** प्रमुख लिपि का पता लगाता है और उसे हर पंक्ति के लिए पिन करता है (देखें **मिश्रित-लिपि सरणियाँ**)। लिपि, रोमनाइज़ की गई पंक्तियाँ, और प्रति-पंक्ति `fallbacks` फ़्लैग लौटाता है — `true` वहाँ जहाँ इंजन विफल हुआ और पंक्ति को अंतिम उपाय के रूप में यूनिवर्सल रूप से लिप्यंतरित किया गया।
+
+```ts
+const { script, lines, fallbacks } = await romanizer.romanizeLines([
+  'สวัสดี',
+  'ชาวโลก',
+]);
+// { script: 'thai', lines: ['swasdi', 'chaolok'], fallbacks: [false, false] }
+```
+
+### `UnsupportedRomanizationError`
+
+जब ऐसी लिपि का रोमनाइज़ेशन करने का प्रयास किया जाता है जिसमें कोई इंजन नहीं है — न अंतर्निर्मित और न ही `options.engines` के माध्यम से इंजेक्ट किया गया — तब फेंका जाता है। प्रोग्रामेटिक प्रसंस्करण के लिए `script` गुण है।
+
+```ts
+try {
+  await romanizer.romanizeLine('مرحبا');
+} catch (err) {
+  if (err instanceof UnsupportedRomanizationError) {
+    console.log(err.script); // 'arabic'
+    // बाहरी API पर फ़ॉलबैक
+  }
+}
+```
+
+## समर्थित लिपियाँ
+
+### स्थानीय (पूर्णतः ऑफ़लाइन)
+
+| लिपि | इंजन | उदाहरण |
+|------|------|--------|
+| यूनिवर्सल *(fallback)* | [transliteration](https://github.com/nickclaw/transliteration) | `Привет` → `Privet` |
+| जापानी | [kuroshiro](https://github.com/sglkc/kuroshiro-ts) + [kuromoji](https://github.com/takuyaa/kuromoji.js) | `こんにちは` → `konnichiha` |
+| मंदारिन | [pinyin-pro](https://github.com/zh-lx/pinyin-pro) | `你好` → `nǐ hǎo` |
+| कैंटोनीज़ | [to-jyutping](https://github.com/CanCLID/to-jyutping) | `佢冇` → `keoi5 mou5` |
+| कोरियाई | [@romanize/korean](https://github.com/kntng/romanize) | `안녕` → `annyeong` |
+| सिरिलिक | [cyrillic-to-translit-js](https://github.com/greybax/CyrillicToTranslitJS) | `Привет` → `Privet` |
+| देवनागरी | [sanscript](https://github.com/indic-transliteration/sanscript) | `नमस्ते` → `namaste` |
+| गुजराती | [sanscript](https://github.com/indic-transliteration/sanscript) | `નમસ્તે` → `namaste` |
+| गुरमुखी | [sanscript](https://github.com/indic-transliteration/sanscript) | `ਨਮਸਤੇ` → `namasate` |
+| तेलुगु | [sanscript](https://github.com/indic-transliteration/sanscript) | `నమస్తే` → `namaste` |
+| कन्नड़ | [sanscript](https://github.com/indic-transliteration/sanscript) | `ನಮಸ್ತೇ` → `namaste` |
+| ओडिया | [sanscript](https://github.com/indic-transliteration/sanscript) | `ନମସ୍ତେ` → `namaste` |
+| तमिल | [tamil-romanizer](https://github.com/haroldalan/tamil-romanizer) | `வணக்கம்` → `vanakkam` |
+| थाई | [@dehoist/romanize-thai](https://github.com/Dehoist/Open-Source) | `สวัสดี` → `swasdi` |
+
+### बाहरी API आवश्यक
+
+| लिपि | विधि |
+|------|------|
+| मलयालम | Google Translate `dt=rm` |
+| बंगाली | Google Translate `dt=rm` |
+| अरबी | Google Translate `dt=rm` |
+| हिब्रू | Google Translate `dt=rm` |
+| अन्य | Google Translate `dt=rm` |
+
+इनका पता लगाने और अपने पसंदीदा API पर स्विच करने के लिए `requiresExternalRomanization()` का उपयोग करें — या API को एक बार **इंजन एडाप्टर** के रूप में प्लग करें और `romanizeLines` को हर लिपि संभालने दें।
+
+## लिपि-विशिष्ट नोट्स
+
+### मिश्रित-लिपि सरणियाँ
+
+`romanizeLines` पूरी सरणी की **प्रमुख** लिपि को हर पंक्ति पर पिन करता है। यह जानबूझकर है: किसी जापानी गीत के भीतर केवल-कांजी वाली पंक्ति अपने आप में चीनी से अप्रभेद्य होती है (कांजी और हान्ज़ी एक ही Unicode ब्लॉक साझा करते हैं), इसलिए केवल पूरी-सरणी का संदर्भ ही उसे सही इंजन पर रूट करता है। जानने योग्य परिणाम:
+
+- सरणी में कहीं भी कोई भी काना पूरी सरणी को `japanese` पर पिन कर देता है — काना निर्णायक प्रमाण है।
+- सरणी के भीतर किसी *भिन्न* गैर-लैटिन लिपि की पंक्ति को भी पिन किए गए इंजन को ही दिया जाता है।
+- शुद्ध-लैटिन पंक्तियाँ (किसी CJK गीत के भीतर अंग्रेज़ी कोरस) को पिन किए गए इंजन को देने के बजाय **जैसी की वैसी लौटाया जाता है**।
+- प्रति-पंक्ति `fallbacks` फ़्लैग बताते हैं कि कब कोई इंजन विफल हुआ और कोई पंक्ति यूनिवर्सल लिप्यंतरण पर फ़ॉलबैक हो गई।
+
+यदि आपको सच्ची प्रति-पंक्ति इंजन रूटिंग चाहिए, तो `romanizeLine` को लूप में कॉल करें — यह प्रति पंक्ति पहचान करता है।
+
+### सिरिलिक पहचान
+
+सिरिलिक स्वचालित रूप से यूक्रेनी विशिष्ट वर्णों (`і`, `ї`, `є`, `ґ`) की पहचान करता है और यूक्रेनी लिप्यंतरण प्रीसेट लागू करता है। अन्य सभी सिरिलिक पाठ डिफ़ॉल्ट रूप से रूसी के रूप में संसाधित होता है।
+
+### कैंटोनीज़ समर्थन
+
+चीनी पाठ डिफ़ॉल्ट रूप से मंदारिन (पिनयिन) है। `RomanizeOptions` में `dialect: 'cantonese'` पास करें ताकि चीनी पाठ को [Jyutping](https://github.com/CanCLID/to-jyutping) में रोमनाइज़ किया जा सके।
+
+```ts
+const { lines } = await romanizer.romanizeLines(['你好世界', '食飯'], {
+  script: 'chinese',
+  dialect: 'cantonese',
+});
+// ['nei5 hou2 sai3 gaai3', 'sik6 faan6']
+```
+
+## लाइसेंस
+
+MIT

package/docs/README.ja.md

@@ -0,0 +1,296 @@
+# lyric-romanizer
+
+[![npm version](https://img.shields.io/npm/v/lyric-romanizer.svg)](https://www.npmjs.com/package/lyric-romanizer)
+[![license](https://img.shields.io/npm/l/lyric-romanizer.svg)](https://github.com/thedavidweng/lyric-romanizer/blob/main/LICENSE)
+
+> **哲学：車輪の再発明をしない。**
+> このプロジェクトは、ゼロからローマ字化ロジックを構築するのではなく、各スクリプトに特化したコミュニティ主導のライブラリを組み合わせる設計思想を採用しています。スクリプト検出、エンジンルーティング、方言処理、統一APIというオーケストレーション層に集中しています。依存関係にあるすべてのローマ字化エンジンは、各分野の専門家によって維持管理されている実績あるライブラリです。それがこのプロジェクトの本質です。
+
+歌詞向けスクリプト検出・ローカルローマ字化エンジン。日本語、中国語（普通話・広東語）、韓国語、キリル文字、インド系文字、タミル語、タイ語の12以上のスクリプトをサポートし、すべてAPIコールなしでローカルで動作します。
+
+[Spotify Karaoke](https://github.com/haroldalan/spotify-karaoke) から抽出。[OpenKara](https://github.com/thedavidweng/openkara) で使用されています。
+
+[English](https://github.com/thedavidweng/lyric-romanizer#readme) | [中文（简体）](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.zh-CN.md) | [中文（粵語）](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.zh-yue.md) | [한국어](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ko.md) | [Русский](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ru.md) | [हिन्दी](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.hi.md) | [தமிழ்](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.ta.md) | [ไทย](https://github.com/thedavidweng/lyric-romanizer/blob/main/docs/README.th.md)
+
+## 特徴
+
+- **APIコール不要** — すべてのローマ字化がローカルで実行される
+- **自動スクリプト検出** — テキストを渡すだけで使用スクリプトを自動判定
+- **12以上のスクリプト** — 日本語、中国語、韓国語、キリル文字、6種類のインド系文字、タミル語、タイ語
+- **広東語サポート** — 普通話ピン音に加え、広東語粤拼（Jyutping）にも対応
+- **軽量検出サブパス** — ローマ字化エンジンを取り込まずに、スクリプト検出（および外部スクリプトの分類）のみをインポート可能
+- **遅延エンジン** — すべてのエンジンは初回使用時に読み込まれ、ローマ字化するまでメインエントリのインポートにコストはかかりません
+- **差し込み可能なエンジン** — 任意の組み込みエンジンを上書きするか、外部でローマ字化するスクリプト向けに独自のアダプターを差し込めます
+- **観測可能なフォールバック** — 行ごとのフラグにより、エンジンが失敗して行が最終手段として翻字されたタイミングがわかります
+- **ウクライナ語対応キリル文字** — ウクライナ固有文字を自動検出し、適切な翻字プリセットを適用
+- **素の Node ESM で動作** — バンドラー不要
+
+## インストール
+
+```bash
+npm install lyric-romanizer
+```
+
+```bash
+yarn add lyric-romanizer
+```
+
+```bash
+pnpm add lyric-romanizer
+```
+
+## クイックスタート
+
+```ts
+import { createRomanizer, detectScript } from 'lyric-romanizer';
+
+const romanizer = createRomanizer();
+
+// スクリプトを自動検出してローマ字化
+const result = await romanizer.romanizeLines(['你好世界', '很高兴认识你']);
+// { script: 'chinese', lines: ['nǐ hǎo shì jiè', 'hěn gāo xìng rèn shi nǐ'], fallbacks: [false, false] }
+
+// 1行だけローマ字化
+const line = await romanizer.romanizeLine('안녕하세요');
+// 'annyeonghaseyo'
+```
+
+> **検出の粒度** — `romanizeLines` は**全行を通して一度だけ**支配的なスクリプトを検出し、すべての行に固定します（意図的な設計です。日本語の曲の中の漢字のみの行も日本語エンジンに到達する必要があり、配列内にかながあれば `japanese` に固定されます）。一方、`romanizeLine` をループで呼び出すと**行ごとに**検出し、各行を異なるエンジンにルーティングする可能性があります。固定されたスクリプトの下では、純粋なラテン文字の行はそのまま返されます。**スクリプトが混在する配列**を参照してください。
+
+## API
+
+### インポート
+
+```ts
+// メインエントリ — ローマ字化エンジン全体
+import {
+  createRomanizer,
+  detectScript,
+  isLatinScript,
+  requiresExternalRomanization,
+  UnsupportedRomanizationError,
+} from 'lyric-romanizer';
+
+// 検出専用サブパス — 軽量、ローマ字化の依存関係なし
+import {
+  detectScript,
+  isLatinScript,
+  requiresExternalRomanization,
+  NON_LATIN_SCRIPT_RE,
+} from 'lyric-romanizer/detector';
+```
+
+### 型定義
+
+```ts
+type ScriptType =
+  | 'japanese' | 'chinese' | 'korean' | 'cyrillic'
+  | 'devanagari' | 'gujarati' | 'gurmukhi' | 'telugu'
+  | 'kannada' | 'odia' | 'tamil' | 'malayalam'
+  | 'bengali' | 'arabic' | 'hebrew' | 'thai'
+  | 'latin' | 'other';
+
+interface Romanizer {
+  romanizeLine(line: string, options?: RomanizeOptions): Promise<string>;
+  romanizeLines(lines: readonly string[], options?: RomanizeOptions): Promise<RomanizeResult>;
+}
+
+// `dialect` は 'chinese' でのみ有効。他のすべてのスクリプトでは無視されます。
+type RomanizeOptions = { script?: ScriptType; dialect?: 'mandarin' | 'cantonese' };
+
+// `fallbacks` は `lines` と対応し、エンジンが失敗して行が最終手段として
+// ユニバーサル翻字された箇所が true になります。
+type RomanizeResult = { script: ScriptType; lines: string[]; fallbacks?: boolean[] };
+
+// エンジンアダプター：自身のスクリプトの1行をローマ字化します。スロー（または
+// リジェクト）するとユニバーサル翻字フォールバックが発動します。
+type RomanizeEngine = (line: string, context: { dialect: 'mandarin' | 'cantonese' }) => string | Promise<string>;
+
+type RomanizerOptions = {
+  japaneseDictPath?: string;
+  engines?: Partial<Record<ScriptType, RomanizeEngine>>;
+};
+```
+
+### `createRomanizer(options?)`
+
+`Romanizer` インスタンスを返すファクトリ関数。すべてのエンジンは初回使用時に遅延読み込みされ、キャッシュされます。読み込みに失敗した場合は、次回の呼び出しで再試行されます。
+
+```ts
+const romanizer = createRomanizer();
+
+// Kuromoji 辞書の CDN パスを上書き（セルフホスティングなど）
+const romanizer = createRomanizer({
+  japaneseDictPath: 'https://my-cdn.com/kuromoji/dict',
+});
+```
+
+#### エンジンアダプター
+
+`options.engines` はスクリプトの組み込みエンジンを上書きします。あるいは、組み込みエンジンを持たないスクリプト（`arabic`、`hebrew`、`malayalam`、`bengali`、`other`）にエンジンを差し込むことで、`romanizeLines` が単一のインターフェースを通じてすべてのスクリプトを処理できるようになります。デフォルトでは、このライブラリは**ネットワークI/Oを一切行いません**。リモートアダプターを差し込むのは、呼び出し側の明示的な判断です。
+
+```ts
+const romanizer = createRomanizer({
+  engines: {
+    // ローカルエンジンを持たないスクリプト向けに独自の外部ローマ字化を用意します。
+    arabic: async (line) => myTransliterationApi(line),
+    // または組み込みエンジンを置き換えます（例：テストでのフェイク）。
+    korean: (line) => myKoreanRomanizer(line),
+  },
+});
+
+await romanizer.romanizeLines(['مرحبا']);
+// { script: 'arabic', lines: [...], fallbacks: [false] } — もうスローしません
+```
+
+組み込み・注入を問わず、エンジンを持たないスクリプトは、引き続き `UnsupportedRomanizationError` をスローします。
+
+### `detectScript(lines)`
+
+与えられたテキスト行の支配的なスクリプトを検出します。まず日本語のかなを判定し（確定的）、その後他のスクリプトを文字数でスコアリングします。
+
+```ts
+detectScript(['こんにちは']);          // 'japanese'
+detectScript(['你好世界']);            // 'chinese'
+detectScript(['Привет']);             // 'cyrillic'
+detectScript(['Hello world']);        // 'latin'
+detectScript(['123 ???']);            // 'other'
+```
+
+### `isLatinScript(lines)`
+
+高速チェック — テキストにラテン文字のみが含まれる場合に `true` を返します（CJK、キリル文字、インド系文字などは含まない）。ローマ字化を完全にスキップするのに便利です。
+
+```ts
+isLatinScript(['Hello world']);  // true
+isLatinScript(['안녕하세요']);    // false
+isLatinScript(['♪♪♪']);         // false（文字なし）
+```
+
+### `requiresExternalRomanization(script)`
+
+組み込みエンジンを持たず、外部APIが必要なスクリプトに対して `true` を返します。軽量な `lyric-romanizer/detector` サブパスからインポートできるため、「外部サービスに分岐すべきか？」の判定にエンジンのペイロードは一切かかりません。
+
+```ts
+requiresExternalRomanization('chinese');   // false
+requiresExternalRomanization('arabic');    // true
+requiresExternalRomanization('malayalam'); // true
+```
+
+### `romanizer.romanizeLine(line, options?)`
+
+1行をローマ字化します。`script` を省略すると、`detectScript` によって**行ごとに**自動検出されます。`romanizeLine` をループで呼び出すと各行が異なるエンジンにルーティングされる可能性があり、配列全体に1つのスクリプトを固定する `romanizeLines` とは異なります。ラテン文字や文字を含まないコンテンツはそのまま返されます。
+
+中国語テキストの場合、`dialect` オプションでローマ字化方式を制御します：`'mandarin'`（デフォルト）はピン音、`'cantonese'` は [Jyutping](https://github.com/CanCLID/to-jyutping) を使用します。他のスクリプトは `dialect` を無視します。
+
+エンジン（組み込み・注入を問わず）を持たないスクリプトの場合、`UnsupportedRomanizationError` を**スローします**。
+
+```ts
+await romanizer.romanizeLine('你好世界');
+// 'nǐ hǎo shì jiè'（デフォルト：普通話/ピン音）
+
+await romanizer.romanizeLine('你好', { dialect: 'cantonese' });
+// 'nei5 hou2' (Jyutping)
+
+await romanizer.romanizeLine('Привет мир');
+// 'Privet mir'
+
+await romanizer.romanizeLine('Hello world');
+// 'Hello world'（そのまま）
+
+await romanizer.romanizeLine('مرحبا');
+// throws UnsupportedRomanizationError { script: 'arabic' }
+```
+
+### `romanizer.romanizeLines(lines, options?)`
+
+複数行を並列でローマ字化します。**全行を通して一度だけ**支配的なスクリプトを検出し、すべての行に固定します（**スクリプトが混在する配列**を参照）。スクリプト、ローマ字化された行、そして行ごとの `fallbacks` フラグを返します。`fallbacks` は、エンジンが失敗して行が最終手段としてユニバーサル翻字された箇所で `true` になります。
+
+```ts
+const { script, lines, fallbacks } = await romanizer.romanizeLines([
+  'สวัสดี',
+  'ชาวโลก',
+]);
+// { script: 'thai', lines: ['swasdi', 'chaolok'], fallbacks: [false, false] }
+```
+
+### `UnsupportedRomanizationError`
+
+エンジン（組み込み、または `options.engines` で注入）を持たないスクリプトをローマ字化しようとした場合にスローされます。プログラム処理用の `script` プロパティを持ちます。
+
+```ts
+try {
+  await romanizer.romanizeLine('مرحبا');
+} catch (err) {
+  if (err instanceof UnsupportedRomanizationError) {
+    console.log(err.script); // 'arabic'
+    // 外部APIにフォールバック
+  }
+}
+```
+
+## サポートされているスクリプト
+
+### ローカル（完全オフライン）
+
+| スクリプト | エンジン | 例 |
+|-----------|---------|-----|
+| ユニバーサル *(fallback)* | [transliteration](https://github.com/nickclaw/transliteration) | `Привет` → `Privet` |
+| 日本語 | [kuroshiro](https://github.com/sglkc/kuroshiro-ts) + [kuromoji](https://github.com/takuyaa/kuromoji.js) | `こんにちは` → `konnichiha` |
+| 中国語（普通話） | [pinyin-pro](https://github.com/zh-lx/pinyin-pro) | `你好` → `nǐ hǎo` |
+| 中国語（広東語） | [to-jyutping](https://github.com/CanCLID/to-jyutping) | `佢冇` → `keoi5 mou5` |
+| 韓国語 | [@romanize/korean](https://github.com/kntng/romanize) | `안녕` → `annyeong` |
+| キリル文字 | [cyrillic-to-translit-js](https://github.com/greybax/CyrillicToTranslitJS) | `Привет` → `Privet` |
+| デーバナーガリー | [sanscript](https://github.com/indic-transliteration/sanscript) | `नमस्ते` → `namaste` |
+| グジャラート語 | [sanscript](https://github.com/indic-transliteration/sanscript) | `નમસ્તે` → `namaste` |
+| グルムキー文字 | [sanscript](https://github.com/indic-transliteration/sanscript) | `ਨਮਸਤੇ` → `namasate` |
+| テルグ語 | [sanscript](https://github.com/indic-transliteration/sanscript) | `నమస్తే` → `namaste` |
+| カンナダ語 | [sanscript](https://github.com/indic-transliteration/sanscript) | `ನಮಸ್ತೇ` → `namaste` |
+| オディア語 | [sanscript](https://github.com/indic-transliteration/sanscript) | `ନମସ୍ତେ` → `namaste` |
+| タミル語 | [tamil-romanizer](https://github.com/haroldalan/tamil-romanizer) | `வணக்கம்` → `vanakkam` |
+| タイ語 | [@dehoist/romanize-thai](https://github.com/Dehoist/Open-Source) | `สวัสดี` → `swasdi` |
+
+### 外部APIが必要
+
+| スクリプト | 方法 |
+|-----------|------|
+| マラヤーラム語 | Google Translate `dt=rm` |
+| ベンガル語 | Google Translate `dt=rm` |
+| アラビア語 | Google Translate `dt=rm` |
+| ヘブライ語 | Google Translate `dt=rm` |
+| その他 | Google Translate `dt=rm` |
+
+`requiresExternalRomanization()` でこれらを検出してお好みのAPIに分岐するか、あるいはAPIを一度**エンジンアダプター**として差し込んで、`romanizeLines` にすべてのスクリプトを処理させることもできます。
+
+## スクリプト別の注意事項
+
+### スクリプトが混在する配列
+
+`romanizeLines` は配列全体の**支配的な**スクリプトをすべての行に固定します。これは意図的な設計です。日本語の曲の中の漢字のみの行は、それ単体では中国語と区別できません（漢字と中国語の漢字は同じUnicodeブロックを共有しているため）。そのため、配列全体の文脈だけが正しいエンジンへのルーティングを可能にします。知っておくべき影響は次のとおりです。
+
+- 配列内のどこかにかなが1文字でもあれば、配列全体が `japanese` に固定されます — かなは決定的な証拠です。
+- 配列内に*異なる*非ラテン文字の行があっても、固定されたエンジンに渡されます。
+- 純粋なラテン文字の行（CJKの曲の中の英語のサビなど）は、固定されたエンジンに渡されず、**そのまま返されます**。
+- 行ごとの `fallbacks` フラグは、エンジンが失敗して行がユニバーサル翻字に劣化した箇所を報告します。
+
+真に行ごとのエンジンルーティングが必要な場合は、`romanizeLine` をループで呼び出してください — こちらは行ごとに検出します。
+
+### キリル文字の検出
+
+キリル文字はウクライナ固有の文字（`і`、`ї`、`є`、`ґ`）を自動検出し、ウクライナ語の翻字プリセットを適用します。その他のキリル文字はロシア語として処理されます。
+
+### 広東語サポート
+
+中国語はデフォルトで普通話（ピン音）になります。`RomanizeOptions` で `dialect: 'cantonese'` を渡すと、中国語テキストを [Jyutping](https://github.com/CanCLID/to-jyutping) でローマ字化します。
+
+```ts
+const { lines } = await romanizer.romanizeLines(['你好世界', '食飯'], {
+  script: 'chinese',
+  dialect: 'cantonese',
+});
+// ['nei5 hou2 sai3 gaai3', 'sik6 faan6']
+```
+
+## ライセンス
+
+MIT