ingglish
Interfaces
PhoneDict
Unified phoneme dictionary type. Entries are ARPAbet arrays, converted from IPA at build time. English and foreign dicts share the same format.
Properties
conventionalCapitals?
optional conventionalCapitals: Set<string>;
Pronouns capitalized by convention, not phonetics (e.g. English "I"). Lowered in contraction output.
disableRColoring?
optional disableRColoring: boolean;
True for non-English languages — disables English R-coloring rules.
entries
entries: Record<string, string[]>;
lang
lang: string;
nonLatinScript?
optional nonLatinScript: boolean;
True for non-Latin scripts (Arabic, CJK, Khmer) — uses Unicode tokenizer.
preprocess()?
optional preprocess: (text) => string;
Pre-process text before tokenization (e.g. Khmer word segmentation).
Parameters
text
string
Returns
string
TranslatedToken
A single token from a translated text, preserving the mapping between original and translated forms. Used by both forward and reverse translation.
Properties
isWord
isWord: boolean;
Whether this token is a word (true) or punctuation/whitespace (false).
matched
matched: boolean;
Whether the word was found in the dictionary (false = heuristic fallback).
original
original: string;
The original text of this token (English for forward, Ingglish for reverse).
translated
translated: string;
The translated text (Ingglish for forward, English for reverse).
TranslateOptions
Properties
format?
optional format: OutputFormat;
Output format.
Default
'ingglish'
lang?
optional lang: string;
Language code (omit or 'en' for English).
Type Aliases
DictLoader()
type DictLoader = (lang) => Promise<PhoneDict>;
Parameters
lang
string
Returns
Promise<PhoneDict>
OutputFormat
type OutputFormat =
| "ingglish"
| "ipa"
| string & {
};
Output format for phoneme conversion.
Functions
loadLangDict()
function loadLangDict(lang): Promise<PhoneDict>;
Load a dictionary, returning it from cache if available. Requires a loader to have been registered via setDictLoader.
Parameters
lang
string
Returns
Promise<PhoneDict>
reverseTranslate()
function reverseTranslate(text, options?): Promise<string>;
Translates Ingglish/IPA text back to the source language. Auto-loads dictionaries on first call. For homophones, uses the most common word.
For English (default): uses the CMU reverse dictionary. For other languages: builds/caches a reverse map from the dictionary.
Parameters
text
string
Text in Ingglish or IPA format
options?
TranslateOptions = {}
Translation options (format, lang)
Returns
Promise<string>
Source language text
reverseTranslateSync()
function reverseTranslateSync(text, options?): string;
Synchronous reverse translation. Dictionary/reverse map must already be loaded.
All languages go through the same pipeline: text → extractTokens → mapTokens(reverseWord) → output
For non-English languages, the reverse map must have been built by a prior
await reverseTranslate(text, { lang }) call.
Parameters
text
string
options?
TranslateOptions = {}
Returns
string
reverseTranslateSyncWithMapping()
function reverseTranslateSyncWithMapping(text, options?): TranslatedToken[];
Like reverseTranslate, but returns token-by-token mappings instead of a string. Each token includes the original text, translation, and whether it matched the dictionary. Dictionary must already be loaded.
Parameters
text
string
options?
TranslateOptions = {}
Returns
setDictLoader()
function setDictLoader(loader): void;
Register a function that loads dictionaries. Called once at application startup (e.g. in the website's entry point).
Parameters
loader
Returns
void
Example
setDictLoader(async (lang) => {
const resp = await fetch(`/ipa-dicts/${lang}.json`);
const entries = await resp.json();
return { entries, lang };
});
translate()
function translate(text, options?): Promise<string>;
Translates text to the specified format. Auto-loads dictionaries on first call.
For English (default): loads the CMU pronunciation dictionary. For non-English languages: loads the dictionary via the registered loader.
Parameters
text
string
The text to translate
options?
TranslateOptions = {}
Translation options (format, lang)
Returns
Promise<string>
The translated text
translateSync()
function translateSync(text, options?): string;
Synchronous forward translation. Dictionary must already be loaded.
All languages go through the same pipeline: text → [preprocess] → extractTokens → renderText → output
Parameters
text
string
options?
TranslateOptions = {}
Returns
string
translateSyncWithMapping()
function translateSyncWithMapping(text, options?): TranslatedToken[];
Like translate, but returns token-by-token mappings instead of a string. Each token includes the original text, translation, and whether it matched the dictionary. Dictionary must already be loaded.
Parameters
text
string
options?
TranslateOptions = {}