@ingglish/fallback 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,119 @@
+import { G2PTrace } from '@ingglish/g2p';
+import { OutputFormat } from '@ingglish/phonemes';
+
+/**
+ * Acronym and initialism handling.
+ *
+ * Handles words that should be spelled out letter-by-letter
+ * (e.g., URL -> "you-are-ell") vs acronyms pronounced as words
+ * (e.g., NASA -> "nasa").
+ */
+
+/**
+ * Phonemes for individual letters (for spelling out acronyms).
+ * Based on how native English speakers pronounce alphabet letters.
+ */
+declare const LETTER_PHONEMES: Record<string, string[]>;
+/**
+ * Known initialisms - derived from INITIALISM_EXPANSIONS for consistency.
+ * These are pronounced as individual letters, NOT as words.
+ *
+ * Excludes acronyms pronounced as words like:
+ * - RAM (ram), ROM (rom), GIF (gif/jif), JPEG (jay-peg)
+ * - JSON (jason), SQL (sequel), NASA, NATO, SCUBA, LASER
+ */
+declare const KNOWN_INITIALISMS: Set<string>;
+/**
+ * Checks if a word should be spelled out as individual letters (initialism).
+ * Only returns true for known initialisms - unknown uppercase words are NOT
+ * automatically treated as initialisms since they might be acronyms pronounced
+ * as words (like NASA, GIF, etc).
+ */
+declare function isInitialism(word: string): boolean;
+/**
+ * Checks if a word is an initialism with a suffix (e.g., "IDs", "TVs", "URLs", "API's").
+ * Returns the base initialism and suffix if matched, null otherwise.
+ */
+declare function parseInitialismWithSuffix(word: string): null | {
+    base: string;
+    suffix: string;
+};
+/**
+ * Translates a word by spelling out each letter.
+ * Used for acronyms like URL, HTML, API.
+ */
+declare function translateAsAcronym(word: string, format?: OutputFormat): string;
+
+/**
+ * British-to-American spelling conversion.
+ *
+ * Converts common British English spellings to their American
+ * equivalents and looks them up in the CMU dictionary.
+ * Used as a fallback when the British spelling isn't found.
+ */
+
+interface BritishMatch {
+    american: string;
+    phonemes: string[];
+}
+/**
+ * Matches a word against British-to-American spelling rules.
+ * Returns the American spelling and its phonemes, or null if no match.
+ */
+declare function matchBritish(word: string): BritishMatch | null;
+
+/**
+ * Fallback strategies for translating unknown words.
+ *
+ * Called when a word isn't in the dictionary. Each strategy ultimately
+ * produces ARPAbet `string[]` (the pipeline IR), which is then passed
+ * through `arpabetToFormat()` for final output.
+ *
+ * Strategy order:
+ * 1. Custom pronunciations (tech terms, brand names)
+ * 2. Initialisms (spell out letters: URL -> you-are-ell)
+ * 3. British spelling normalization (colour -> color)
+ * 4. Compound word splitting (github -> git + hub)
+ * 5. Stemming (find known base word + known suffix)
+ * 6. Rule-based grapheme-to-phoneme
+ */
+
+type WordDiagnosis = {
+    americanSpelling: string;
+    phonemes: string[];
+    strategy: 'british';
+} | {
+    parts: string[];
+    strategy: 'compound';
+} | {
+    phonemes: string[];
+    strategy: 'custom';
+} | {
+    prefix?: string;
+    stem: string;
+    strategy: 'stemming';
+    suffix?: string;
+} | {
+    strategy: 'g2p';
+    trace: G2PTrace;
+} | {
+    strategy: 'initialism';
+};
+
+/**
+ * Diagnoses an unknown word by determining which fallback strategy handles it
+ * and collecting diagnostic data for display.
+ *
+ * Returns null for obvious non-words (3+ repeated chars, no vowels).
+ */
+declare function diagnoseUnknown(word: string): null | WordDiagnosis;
+/**
+ * Attempts all strategies to translate an unknown word.
+ *
+ * @param word The unknown word
+ * @param format The output format
+ * @returns The translated word
+ */
+declare function translateUnknown(word: string, format?: OutputFormat): string;
+
+export { KNOWN_INITIALISMS, LETTER_PHONEMES, type WordDiagnosis, diagnoseUnknown, isInitialism, matchBritish, parseInitialismWithSuffix, translateAsAcronym, translateUnknown };

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import { G2PTrace } from '@ingglish/g2p';
+import { OutputFormat } from '@ingglish/phonemes';
+
+/**
+ * Acronym and initialism handling.
+ *
+ * Handles words that should be spelled out letter-by-letter
+ * (e.g., URL -> "you-are-ell") vs acronyms pronounced as words
+ * (e.g., NASA -> "nasa").
+ */
+
+/**
+ * Phonemes for individual letters (for spelling out acronyms).
+ * Based on how native English speakers pronounce alphabet letters.
+ */
+declare const LETTER_PHONEMES: Record<string, string[]>;
+/**
+ * Known initialisms - derived from INITIALISM_EXPANSIONS for consistency.
+ * These are pronounced as individual letters, NOT as words.
+ *
+ * Excludes acronyms pronounced as words like:
+ * - RAM (ram), ROM (rom), GIF (gif/jif), JPEG (jay-peg)
+ * - JSON (jason), SQL (sequel), NASA, NATO, SCUBA, LASER
+ */
+declare const KNOWN_INITIALISMS: Set<string>;
+/**
+ * Checks if a word should be spelled out as individual letters (initialism).
+ * Only returns true for known initialisms - unknown uppercase words are NOT
+ * automatically treated as initialisms since they might be acronyms pronounced
+ * as words (like NASA, GIF, etc).
+ */
+declare function isInitialism(word: string): boolean;
+/**
+ * Checks if a word is an initialism with a suffix (e.g., "IDs", "TVs", "URLs", "API's").
+ * Returns the base initialism and suffix if matched, null otherwise.
+ */
+declare function parseInitialismWithSuffix(word: string): null | {
+    base: string;
+    suffix: string;
+};
+/**
+ * Translates a word by spelling out each letter.
+ * Used for acronyms like URL, HTML, API.
+ */
+declare function translateAsAcronym(word: string, format?: OutputFormat): string;
+
+/**
+ * British-to-American spelling conversion.
+ *
+ * Converts common British English spellings to their American
+ * equivalents and looks them up in the CMU dictionary.
+ * Used as a fallback when the British spelling isn't found.
+ */
+
+interface BritishMatch {
+    american: string;
+    phonemes: string[];
+}
+/**
+ * Matches a word against British-to-American spelling rules.
+ * Returns the American spelling and its phonemes, or null if no match.
+ */
+declare function matchBritish(word: string): BritishMatch | null;
+
+/**
+ * Fallback strategies for translating unknown words.
+ *
+ * Called when a word isn't in the dictionary. Each strategy ultimately
+ * produces ARPAbet `string[]` (the pipeline IR), which is then passed
+ * through `arpabetToFormat()` for final output.
+ *
+ * Strategy order:
+ * 1. Custom pronunciations (tech terms, brand names)
+ * 2. Initialisms (spell out letters: URL -> you-are-ell)
+ * 3. British spelling normalization (colour -> color)
+ * 4. Compound word splitting (github -> git + hub)
+ * 5. Stemming (find known base word + known suffix)
+ * 6. Rule-based grapheme-to-phoneme
+ */
+
+type WordDiagnosis = {
+    americanSpelling: string;
+    phonemes: string[];
+    strategy: 'british';
+} | {
+    parts: string[];
+    strategy: 'compound';
+} | {
+    phonemes: string[];
+    strategy: 'custom';
+} | {
+    prefix?: string;
+    stem: string;
+    strategy: 'stemming';
+    suffix?: string;
+} | {
+    strategy: 'g2p';
+    trace: G2PTrace;
+} | {
+    strategy: 'initialism';
+};
+
+/**
+ * Diagnoses an unknown word by determining which fallback strategy handles it
+ * and collecting diagnostic data for display.
+ *
+ * Returns null for obvious non-words (3+ repeated chars, no vowels).
+ */
+declare function diagnoseUnknown(word: string): null | WordDiagnosis;
+/**
+ * Attempts all strategies to translate an unknown word.
+ *
+ * @param word The unknown word
+ * @param format The output format
+ * @returns The translated word
+ */
+declare function translateUnknown(word: string, format?: OutputFormat): string;
+
+export { KNOWN_INITIALISMS, LETTER_PHONEMES, type WordDiagnosis, diagnoseUnknown, isInitialism, matchBritish, parseInitialismWithSuffix, translateAsAcronym, translateUnknown };