which-dialect 0.1.1 → 0.3.0

package/dist/index.js

@@ -107,6 +107,24 @@ export function createDictionary(options) {
             const m = await meta();
             return m.picks ? loadOnce('picks.json') : [];
         },
+        async checker() {
+            const m = await meta();
+            return m.checker ? loadOnce('checker.json') : {};
+        },
+        async syllables() {
+            const m = await meta();
+            return m.syllables ? loadOnce('syllables.json') : {};
+        },
+        async frames() {
+            const m = await meta();
+            if (!m.frames)
+                return { frames: [], words: {} };
+            const stored = await loadOnce('frames.json');
+            return {
+                frames: stored.frames,
+                words: Object.fromEntries(Object.entries(stored.words).map(([k, w]) => [k, { ...w, choices: w.choices.map((c) => fromStored(c, m.regions)) }])),
+            };
+        },
         async pronouns({ listener, region, speaker, exclude = DEFAULT_EXCLUDED_LABELS } = {}) {
             const m = await meta();
             if (!m.pronouns)
@@ -132,3 +150,7 @@ export function createDictionary(options) {
     };
 }
 export * from "./translate.js";
+export * from "./check.js";
+export * from "./text.js";
+export * from "./phrasebook.js";
+export * from "./review.js";

package/dist/phrasebook.d.ts

@@ -0,0 +1,80 @@
+import { type Translator, type TranslatorOptions } from './translate.ts';
+export type FrameOptions = {
+    /** The language to say it in, e.g. "vi". */
+    lang: string;
+    /** Region or region group; its words come first, and words only used elsewhere are left out. */
+    region?: string;
+    /** Who you're talking to, as a pronoun-table row id; without it, the table's default row. */
+    listener?: string;
+    /** The speaker's gender, for pronouns that depend on it. */
+    speaker?: 'male' | 'female';
+    /** 'casual' allows colloquial words (Southern "hông", "tui"); otherwise they're left out. */
+    register?: 'casual' | 'neutral' | 'polite';
+};
+/** One piece of a filled frame, with why it was chosen, for highlighting and explanations. */
+export type FramePart = {
+    text: string;
+    /** Fixed wording, a frame word ({WHERE}), a pronoun ({I}) or a content slot ({place}). */
+    kind: 'fixed' | 'word' | 'pronoun' | 'content';
+    slot?: string;
+    /** e.g. "where (Central)", "“I”, talking to your parents". */
+    why?: string;
+    regions?: string[];
+    /** For content slots given in English: the English, and whether no translation was found. */
+    from?: string;
+    untranslated?: boolean;
+};
+export type FilledFrame = {
+    id: string;
+    topic: string;
+    /** The English way to say it, with slots filled when given. */
+    en: string;
+    /** The sentence; open content slots stay as {name}. */
+    text: string;
+    parts: FramePart[];
+    /** The content slots and their parts of speech. */
+    slots: {
+        name: string;
+        pos: 'noun' | 'verb' | 'adj';
+    }[];
+    /** true when every content slot is filled (and translated). */
+    complete: boolean;
+};
+/** A content slot value: English (translated for you) or `{ text }` in the target language. */
+export type SlotValue = string | {
+    text: string;
+};
+/** A frame recognized in a sentence in the language itself, and what the frame says should change. */
+export type FrameMatch = {
+    frame: {
+        id: string;
+        en: string;
+    };
+    /** The sentence as the frame would have it, for the given region, listener and register. */
+    text: string;
+    changes: {
+        slot: string;
+        from: string;
+        to: string;
+        why: string;
+    }[];
+};
+export type Phrasebook = {
+    /** The language's frames, filled for the region, listener and register, with content slots open. */
+    frames(options: FrameOptions & {
+        topic?: string;
+    }): Promise<FilledFrame[]>;
+    /** One frame with its content slots filled. Unknown ids throw, listing the valid ones. */
+    render(id: string, options: FrameOptions & {
+        slots?: Record<string, SlotValue>;
+    }): Promise<FilledFrame>;
+    /** The frame an English sentence (or clause) follows, filled with its slot values; null when none. */
+    match(english: string, options: FrameOptions): Promise<FilledFrame | null>;
+    /** Frames a sentence in the language itself follows, with the changes the frame suggests. */
+    matchFrames(sentence: string, options: FrameOptions): Promise<FrameMatch[]>;
+};
+export type PhrasebookOptions = TranslatorOptions & {
+    /** Share a translator (and its dictionaries) instead of creating one. */
+    translator?: Translator;
+};
+export declare function createPhrasebook(options?: PhrasebookOptions): Phrasebook;

package/dist/phrasebook.js

@@ -0,0 +1,254 @@
+// Sentence frames: common sentences with slots ("Where is {place}?" → "{place} ở {WHERE}?"), filled for a
+// region, a listener and a register. The frames, their words and the pronoun table are the language's data
+// (frames.json, pronouns.json), so this file has no language-specific rules: it picks words by region and
+// labels, fills pronouns from the pronoun table, and translates content slots with the translator.
+//
+// Three directions: list and fill frames (`frames`, `render`), recognize an English sentence as a frame
+// (`match`), and recognize a frame in a sentence in the language itself (`matchFrames`), which is how the
+// journal review checks a sentence against frames ("Bạn có đi?" is the yes/no frame missing "không").
+import { createDictionary, resolveRegion } from "./index.js";
+import { matchCase, plain } from "./text.js";
+import { createTranslator } from "./translate.js";
+import { FRAME_PRONOUNS, } from "./types.js";
+const SLOT = /\{([A-Za-z_]+)\}/g;
+// Words for a casual register only.
+const CASUAL = new Set(['colloquial', 'informal', 'familiar', 'slang', 'Internet']);
+const PERSON_NAMES = {
+    self: 'I', addressee: 'you', third: 'he/she', selfPlural: 'we', addresseePlural: 'you (plural)', thirdPlural: 'they',
+};
+const lowerFirst = (s) => s.charAt(0).toLowerCase() + s.slice(1);
+const quote = (s) => `“${s}”`;
+// Words and their accent-less forms ("tôi", "toi"), longest first so "chúng tôi" wins over "tôi".
+const withPlain = (words) => [...new Set(words.flatMap((w) => [w, plain(w)]))].sort((a, b) => b.length - a.length);
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// English sentences compare without case, curly quotes, extra spaces or the final punctuation.
+const normalizeEn = (s) => s.toLowerCase().replace(/[’‘]/g, "'").replace(/\s+/g, ' ').trim().replace(/[.!?…]+$/, '').trim();
+// Spaces after filling: one between words, none before punctuation or after an empty slot.
+const tidy = (s) => s.replace(/\s+/g, ' ').replace(/\s+([.,!?…])/g, '$1').trim();
+function choose(choices, s) {
+    return choices
+        .filter((c) => !s.wanted || c.regions.some((r) => s.wanted.has(r)))
+        .filter((c) => c.when !== 'respect' || s.row?.respect)
+        .filter((c) => s.casual || !c.labels.some((l) => CASUAL.has(l)))
+        .map((c, i) => ({ c, i, regional: s.wanted && c.regionTagged ? 1 : 0, casual: s.casual && c.labels.some((l) => CASUAL.has(l)) ? 1 : 0 }))
+        .sort((a, b) => b.casual - a.casual || b.regional - a.regional || a.i - b.i)[0]?.c;
+}
+function pronounChoices(row, slot) {
+    const p = FRAME_PRONOUNS[slot];
+    if (!row || !p)
+        return [];
+    return row[p.person].filter((c) => p.inclusive === undefined || c.inclusive === undefined || c.inclusive === p.inclusive);
+}
+export function createPhrasebook(options = {}) {
+    const cache = new Map();
+    const dict = (lang) => {
+        let d = cache.get(lang);
+        if (!d) {
+            d = options.dictionary?.(lang) ?? createDictionary({ lang, baseUrl: options.baseUrl?.(lang), load: options.load?.(lang) });
+            cache.set(lang, d);
+        }
+        return d;
+    };
+    const translator = options.translator ?? createTranslator({ ...options, dictionary: dict });
+    async function setting(o) {
+        const d = dict(o.lang);
+        const [meta, data] = await Promise.all([d.meta(), d.frames()]);
+        // An unknown listener throws, listing the valid ones (as the translator does).
+        if (meta.pronouns && o.listener)
+            await d.pronouns({ listener: o.listener });
+        const rows = meta.pronouns ? await d.pronouns({ region: o.region, speaker: o.speaker }) : [];
+        const row = o.listener ? rows.find((r) => r.id === o.listener) : rows.find((r) => r.default);
+        return { meta, data, rows, row, wanted: resolveRegion(meta, o.region), casual: o.register === 'casual' };
+    }
+    // The word for a frame word or pronoun slot, with why; empty when the slot has no word here (no "ạ"
+    // unless the listener's row is marked respect).
+    function slotWord(name, s) {
+        const words = s.data.words[name];
+        if (words) {
+            const c = choose(words.choices, s);
+            if (!c)
+                return { text: '', kind: 'word', slot: name };
+            return {
+                text: c.word, kind: 'word', slot: name, regions: c.regionTagged ? c.regions : undefined,
+                why: `${words.meaning}${c.regionTagged ? ` (${c.regions.join(', ')})` : ''}${c.note ? `: ${c.note}` : ''}`,
+            };
+        }
+        const c = choose(pronounChoices(s.row, name), s);
+        const person = PERSON_NAMES[FRAME_PRONOUNS[name]?.person ?? ''];
+        if (!c)
+            return { text: '', kind: 'pronoun', slot: name };
+        return {
+            text: c.word, kind: 'pronoun', slot: name, regions: c.regionTagged ? c.regions : undefined,
+            why: `“${person}”${s.row && !s.row.default ? `, talking to ${lowerFirst(s.row.label)}` : ''}`,
+        };
+    }
+    async function content(frame, name, value, o) {
+        if (value === undefined)
+            return { text: `{${name}}`, kind: 'content', slot: name };
+        if (typeof value !== 'string')
+            return { text: value.text, kind: 'content', slot: name };
+        const english = value.trim().replace(/^(the|a|an|some)\s+/i, '');
+        const [group] = await translator.translate(english, {
+            from: 'en', to: o.lang, toRegion: o.region, pos: frame.slots[name], register: o.register, limit: 1,
+        }).catch(() => []);
+        const word = group?.translations[0]?.word;
+        return word
+            ? { text: word, kind: 'content', slot: name, from: value, why: `“${english}”`, regions: group.translations[0].regionTagged ? group.translations[0].regions : undefined }
+            : { text: value, kind: 'content', slot: name, from: value, untranslated: true };
+    }
+    async function fill(frame, o, s, values = {}) {
+        const parts = [];
+        let last = 0;
+        for (const m of frame.text.matchAll(SLOT)) {
+            if (m.index > last)
+                parts.push({ text: frame.text.slice(last, m.index), kind: 'fixed' });
+            const name = m[1];
+            parts.push(frame.slots[name] ? await content(frame, name, values[name], o) : slotWord(name, s));
+            last = m.index + m[0].length;
+        }
+        if (last < frame.text.length)
+            parts.push({ text: frame.text.slice(last), kind: 'fixed' });
+        let text = tidy(parts.map((p) => p.text).join(''));
+        if (!frame.clause)
+            text = text.charAt(0).toUpperCase() + text.slice(1);
+        const slots = Object.entries(frame.slots).map(([name, pos]) => ({ name, pos }));
+        const en = Object.keys(frame.slots).reduce((s, name) => (typeof values[name] === 'string' ? s.replace(`{${name}}`, values[name]) : s), frame.en[0]);
+        return {
+            id: frame.id, topic: frame.topic, en, text,
+            parts: parts.filter((p) => p.text),
+            slots,
+            complete: slots.every(({ name }) => values[name] !== undefined) && !parts.some((p) => p.untranslated),
+        };
+    }
+    async function frameById(id, o) {
+        const s = await setting(o);
+        const frame = s.data.frames.find((f) => f.id === id);
+        if (!frame) {
+            throw new Error(`which-dialect: unknown frame "${id}" for ${s.meta.name}. Use one of: ${s.data.frames.map((f) => f.id).join(', ') || '(none)'}`);
+        }
+        return { frame, s };
+    }
+    return {
+        async frames(o) {
+            const s = await setting(o);
+            return Promise.all(s.data.frames.filter((f) => !o.topic || f.topic === o.topic).map((f) => fill(f, o, s)));
+        },
+        async render(id, o) {
+            const { frame, s } = await frameById(id, o);
+            return fill(frame, o, s, o.slots);
+        },
+        async match(english, o) {
+            const s = await setting(o);
+            const sentence = normalizeEn(english);
+            for (const frame of s.data.frames) {
+                for (const template of frame.en) {
+                    const names = [];
+                    const pattern = escape(normalizeEn(template)).replace(/\\\{([A-Za-z_]+)\\\}/g, (_, name) => {
+                        names.push(name);
+                        return '(.+?)';
+                    });
+                    const m = new RegExp(`^${pattern}$`, 'u').exec(sentence);
+                    if (!m)
+                        continue;
+                    const values = Object.fromEntries(names.map((n, i) => [n, m[i + 1]]));
+                    const filled = await fill(frame, o, s, values);
+                    return { ...filled, en: english.trim() };
+                }
+            }
+            return null;
+        },
+        async matchFrames(sentence, o) {
+            const s = await setting(o);
+            const d = dict(o.lang);
+            // Every pronoun of a column, in every row and region: a frame position decides it's a pronoun.
+            const allRows = s.meta.pronouns ? await d.pronouns({ exclude: [] }) : [];
+            const terminal = /[?]\s*$/.test(sentence) ? '?' : '';
+            const core = sentence.trim().replace(/[.!?…]+$/, '').trim();
+            const out = [];
+            for (const frame of s.data.frames) {
+                if (frame.text.trim().endsWith('?') !== (terminal === '?'))
+                    continue;
+                const tokens = [...frame.text.replace(/[.!?…]+\s*$/, '').matchAll(/\{([A-Za-z_]+)\}|[^{]+/g)].map((m) => m[1] ? { slot: m[1] } : { fixed: m[0] });
+                // Frames without fixed words ("{thing} {HOW}?") match only with every word present; frames with
+                // fixed words can spot a missing required word ("Bạn có đi?" → "… không?"). Frames with neither
+                // fixed words nor frame words ("{I} {quality}.") would match almost anything, so they're skipped.
+                const anchored = tokens.some((t) => t.fixed && /\p{L}/u.test(t.fixed));
+                if (!anchored && !tokens.some((t) => t.slot && s.data.words[t.slot]))
+                    continue;
+                const slots = [];
+                let pattern = '';
+                for (const t of tokens) {
+                    if (t.fixed !== undefined) {
+                        pattern += t.fixed.trim() ? `\\s*${escape(t.fixed.trim()).replace(/\s+/g, '\\s+')}\\s*` : '\\s*';
+                        continue;
+                    }
+                    const name = t.slot;
+                    if (frame.slots[name]) {
+                        slots.push({ name, kind: 'content', optional: false });
+                        pattern += '(.+?)';
+                    }
+                    else if (s.data.words[name]) {
+                        const alts = withPlain(s.data.words[name].choices.map((c) => c.word)).map(escape);
+                        const optional = Boolean(s.data.words[name].optional) || anchored;
+                        slots.push({ name, kind: 'word', optional });
+                        pattern += `(${alts.join('|')})${optional ? '?' : ''}`;
+                    }
+                    else {
+                        const alts = withPlain(allRows.flatMap((r) => pronounChoices(r, name)).map((c) => c.word));
+                        if (!alts.length)
+                            continue;
+                        slots.push({ name, kind: 'pronoun', optional: false });
+                        pattern += `(${alts.map(escape).join('|')})`;
+                    }
+                }
+                const m = new RegExp(`^${pattern}$`, 'iu').exec(core);
+                if (!m)
+                    continue;
+                const changes = [];
+                const filled = {};
+                slots.forEach((slot, i) => {
+                    let captured = m[i + 1] ?? '';
+                    filled[slot.name] = captured;
+                    if (slot.kind === 'content')
+                        return;
+                    // A word missing its accents in a frame position ("Toi" where the frame has a pronoun) is that word.
+                    const known = slot.kind === 'word'
+                        ? s.data.words[slot.name].choices.map((c) => c.word)
+                        : allRows.flatMap((r) => pronounChoices(r, slot.name)).map((c) => c.word);
+                    if (captured && !known.includes(captured.toLowerCase())) {
+                        const accented = known.find((w) => plain(w) === captured.toLowerCase());
+                        if (accented) {
+                            const fixed = matchCase(captured, accented);
+                            changes.push({ slot: slot.name, from: captured, to: fixed, why: `${quote(fixed)} needs its accents` });
+                            filled[slot.name] = captured = fixed;
+                        }
+                    }
+                    const expected = slotWord(slot.name, s);
+                    if (slot.kind === 'pronoun') {
+                        // Pronouns change only for a chosen listener: in a journal, "Má" may be who you write about.
+                        const fits = pronounChoices(s.row, slot.name).some((c) => c.word === captured.toLowerCase());
+                        if (o.listener && expected.text && !fits) {
+                            filled[slot.name] = matchCase(captured, expected.text);
+                            changes.push({ slot: slot.name, from: captured, to: filled[slot.name], why: expected.why ?? '' });
+                        }
+                        return;
+                    }
+                    const words = s.data.words[slot.name];
+                    const allowed = words.choices.filter((c) => choose([c], s));
+                    if (captured && !allowed.some((c) => c.word === captured.toLowerCase()) && expected.text) {
+                        filled[slot.name] = matchCase(captured, expected.text);
+                        changes.push({ slot: slot.name, from: captured, to: filled[slot.name], why: expected.why ?? '' });
+                    }
+                    else if (!captured && !words.optional && expected.text) {
+                        filled[slot.name] = expected.text;
+                        changes.push({ slot: slot.name, from: '', to: expected.text, why: `${words.meaning}: this frame needs it` });
+                    }
+                });
+                let text = tidy(frame.text.replace(/[.!?…]+\s*$/, '').replace(SLOT, (_, name) => filled[name] ?? ''));
+                text = matchCase(core, text) + (terminal || sentence.trim().match(/[.!?…]+$/)?.[0] || '');
+                out.push({ frame: { id: frame.id, en: frame.en[0] }, text, changes });
+            }
+            return out;
+        },
+    };
+}

package/dist/review.d.ts

@@ -0,0 +1,56 @@
+import { type CheckRule } from './check.ts';
+import { type FrameOptions } from './phrasebook.ts';
+import { type TranslatorOptions } from './translate.ts';
+export type ReviewOptions = FrameOptions & {
+    /** The learner's own language, for the parts written in it (default "en"). */
+    base?: string;
+};
+export type ReviewChange = {
+    /** What was written (empty when a missing word was added). */
+    from: string;
+    to: string;
+    /** One sentence for the learner. */
+    why: string;
+    /** 'translated' (a base-language word), 'frame' (a sentence frame), or the checker rule. */
+    kind: 'translated' | 'frame' | CheckRule;
+};
+/** A checker suggestion that wasn't applied ("end with ạ"), for the learner to consider. */
+export type ReviewHint = {
+    rule: CheckRule;
+    text: string;
+    message: string;
+    suggestions: string[];
+};
+export type ReviewSentence = {
+    /** Offsets of the sentence in Review.text, including its final punctuation. */
+    start: number;
+    end: number;
+    original: string;
+    /** The sentence split by language, e.g. [{ text: 'Hôm nay tôi đi', lang: 'vi' }, { text: 'market', lang: 'en' }, …]. */
+    parts: {
+        text: string;
+        lang: string;
+    }[];
+    corrected: string;
+    changes: ReviewChange[];
+    hints: ReviewHint[];
+    /** Sentence frames the sentence follows or was built from: the frame's English and its pattern. */
+    frames: {
+        id: string;
+        en: string;
+        text: string;
+    }[];
+    /** Parts the review couldn't handle (longer base-language text that follows no frame), left as written. */
+    unchecked: string[];
+};
+export type Review = {
+    /** The entry, in Unicode NFC form; sentence offsets refer to it. */
+    text: string;
+    /** The whole entry with every sentence corrected. */
+    corrected: string;
+    sentences: ReviewSentence[];
+};
+export type Reviewer = {
+    review(entry: string, options: ReviewOptions): Promise<Review>;
+};
+export declare function createReviewer(options?: TranslatorOptions): Reviewer;

package/dist/review.js

@@ -0,0 +1,201 @@
+// Reviewing a journal entry written in the target language, the learner's own language, or a mix of both
+// ("Hôm nay tôi đi market với má"). For each sentence:
+//
+//   1. Each word is marked as the target or the base language, from the two dictionaries alone (accents and
+//      syllables, headwords, inflected forms); words that could be either take their neighbors' language.
+//   2. Base-language parts are replaced: a whole sentence or clause that follows a sentence frame is filled
+//      in ("but it was expensive" → "nhưng mắc quá"), short phrases are translated word by word ("market" →
+//      "chợ"), and anything longer is listed as unchecked rather than guessed.
+//   3. The grammar checker runs on the whole entry, so consistency checks see every sentence ("tôi" here,
+//      "tui" there); its errors and warnings are applied, its suggestions returned as hints.
+//   4. The corrected sentence is checked against sentence frames ("Bạn có đi?" → "Bạn có đi không?").
+//
+// Everything is rule-based and runs on the language's data: no API, and nothing language-specific here.
+import { createChecker } from "./check.js";
+import { createDictionary } from "./index.js";
+import { createPhrasebook } from "./phrasebook.js";
+import { plain, sentencesOf, units } from "./text.js";
+import { createTranslator } from "./translate.js";
+// The longest base-language phrase translated word by word; longer ones need a frame.
+const MAX_TRANSLATED_UNITS = 3;
+const TERMINAL = /^[.!?…]+/;
+export function createReviewer(options = {}) {
+    const cache = new Map();
+    const dict = (lang) => {
+        let d = cache.get(lang);
+        if (!d) {
+            d = options.dictionary?.(lang) ?? createDictionary({ lang, baseUrl: options.baseUrl?.(lang), load: options.load?.(lang) });
+            cache.set(lang, d);
+        }
+        return d;
+    };
+    const translator = createTranslator({ ...options, dictionary: dict });
+    const phrasebook = createPhrasebook({ ...options, dictionary: dict, translator });
+    const checker = createChecker({ ...options, dictionary: dict });
+    // Which language each unit is in. A unit the target knows and the base doesn't is the target's, and the
+    // other way round; units both or neither know ("an", "to", names) take the nearest decided neighbor's.
+    // In syllable languages, a base-language word that's a target syllable only once accents are added
+    // ("but": bút) is the base language's; a word only the target knows without its accents ("khong") is
+    // still the target's.
+    async function languages(list, lang, base) {
+        const target = dict(lang);
+        const syllables = await target.syllables();
+        const syllableLanguage = Object.keys(syllables).length > 0;
+        const plainSyllables = syllableLanguage ? new Set(Object.keys(syllables).map(plain)) : new Set();
+        // 'exact': a target word as written; 'accents': one only with accents added ("khong" → "không").
+        const targetKnows = async (u) => {
+            const lower = u.text.toLowerCase();
+            if (!syllableLanguage)
+                return (await target.lookup(lower)).length > 0 ? 'exact' : false;
+            if (lower in syllables || lower !== plain(lower))
+                return 'exact';
+            return plainSyllables.has(lower) ? 'accents' : false;
+        };
+        const baseKnows = async (u) => (await translator.senses(u.text, { from: base }).catch(() => [])).length > 0;
+        const marks = await Promise.all(list.map(async (u) => {
+            if (/\d/.test(u.text))
+                return '?';
+            const [t, b] = await Promise.all([targetKnows(u), baseKnows(u)]);
+            if (t === 'exact')
+                return b ? '?' : lang;
+            if (b)
+                return base;
+            return t === 'accents' ? lang : '?';
+        }));
+        return marks.map((m, i) => {
+            if (m !== '?')
+                return m;
+            for (let d = 1; d < marks.length; d++) {
+                if (i - d >= 0 && marks[i - d] !== '?')
+                    return marks[i - d];
+                if (i + d < marks.length && marks[i + d] !== '?')
+                    return marks[i + d];
+            }
+            return lang;
+        });
+    }
+    return {
+        async review(entry, o) {
+            const text = entry.normalize('NFC');
+            const base = o.base ?? 'en';
+            const meta = await dict(o.lang).meta();
+            // A frame as shown to the learner: its English and its pattern for these settings, slots open.
+            const frameInfo = new Map();
+            const frameOf = async (id) => {
+                if (!frameInfo.has(id)) {
+                    const f = await phrasebook.render(id, o);
+                    frameInfo.set(id, { id, en: f.en, text: f.text });
+                }
+                return frameInfo.get(id);
+            };
+            const drafts = [];
+            for (const list of sentencesOf(text, units(text))) {
+                const start = list[0].start;
+                const coreEnd = list[list.length - 1].end;
+                const end = coreEnd + (TERMINAL.exec(text.slice(coreEnd))?.[0].length ?? 0);
+                const langs = await languages(list, o.lang, base);
+                const groups = [];
+                list.forEach((u, i) => {
+                    if (groups.length && groups[groups.length - 1].lang === langs[i])
+                        groups[groups.length - 1].units.push(u);
+                    else
+                        groups.push({ lang: langs[i], units: [u] });
+                });
+                const draft = {
+                    start, coreEnd, end, replacements: [], frames: [], unchecked: [],
+                    parts: groups.map((g) => ({ text: text.slice(g.units[0].start, g.units[g.units.length - 1].end), lang: g.lang })),
+                };
+                const whole = groups.length === 1 && groups[0].lang === base;
+                for (const g of groups.filter((g) => g.lang === base)) {
+                    const from = text.slice(g.units[0].start, g.units[g.units.length - 1].end);
+                    const at = { start: g.units[0].start, end: g.units[g.units.length - 1].end };
+                    // A whole sentence is matched with its own punctuation ("Where is the bathroom?").
+                    const frame = await phrasebook.match(whole ? text.slice(start, end) : from, o);
+                    if (frame && frame.complete) {
+                        let to = frame.text.replace(/[.!?…]+$/, '');
+                        if (!whole && g.units[0].start !== start)
+                            to = to.charAt(0).toLowerCase() + to.slice(1);
+                        const info = await frameOf(frame.id);
+                        draft.replacements.push({ ...at, to, change: { kind: 'frame', from, to, why: `Sentence frame “${info.en}”` } });
+                        draft.frames.push(info);
+                        continue;
+                    }
+                    if (!whole && g.units.length <= MAX_TRANSLATED_UNITS) {
+                        const english = from.replace(/^(the|a|an)\s+/i, '');
+                        const [group] = await translator.translate(english, { from: base, to: o.lang, toRegion: o.region, register: o.register, limit: 1 }).catch(() => []);
+                        const word = group?.translations[0]?.word;
+                        if (word) {
+                            draft.replacements.push({ ...at, to: word, change: { kind: 'translated', from, to: word, why: `“${english}” in ${meta.name}` } });
+                            continue;
+                        }
+                    }
+                    draft.unchecked.push(from);
+                }
+                drafts.push(draft);
+            }
+            // The entry with base-language parts replaced, keeping where each sentence now is.
+            let draftText = '';
+            let cursor = 0;
+            const placed = [];
+            for (const d of drafts) {
+                draftText += text.slice(cursor, d.start);
+                const s = draftText.length;
+                let core = text.slice(d.start, d.coreEnd);
+                for (const r of [...d.replacements].sort((a, b) => b.start - a.start)) {
+                    core = core.slice(0, r.start - d.start) + r.to + core.slice(r.end - d.start);
+                }
+                if (/\p{Lu}/u.test(text.charAt(d.start)))
+                    core = core.charAt(0).toUpperCase() + core.slice(1);
+                draftText += core + text.slice(d.coreEnd, d.end);
+                placed.push({ start: s, coreEnd: s + core.length, end: draftText.length });
+                cursor = d.end;
+            }
+            draftText += text.slice(cursor);
+            // 3. The checker on the whole entry; 4. frames on each corrected sentence.
+            const { issues } = await checker.check(draftText, { lang: o.lang, region: o.region, listener: o.listener, about: undefined, speaker: o.speaker });
+            const sentences = [];
+            for (const [i, d] of drafts.entries()) {
+                const p = placed[i];
+                const mine = issues.filter((x) => x.start >= p.start && x.end <= p.coreEnd);
+                const changes = d.replacements.sort((a, b) => a.start - b.start).map((r) => r.change);
+                const hints = [];
+                let core = draftText.slice(p.start, p.coreEnd);
+                let lastStart = Infinity;
+                for (const x of [...mine].sort((a, b) => b.start - a.start)) {
+                    const applies = (x.severity === 'error' || x.severity === 'warning') && x.suggestions.length && x.end <= lastStart;
+                    if (!applies) {
+                        hints.push({ rule: x.rule, text: x.text, message: x.message, suggestions: x.suggestions });
+                        continue;
+                    }
+                    core = core.slice(0, x.start - p.start) + x.suggestions[0] + core.slice(x.end - p.start);
+                    changes.push({ kind: x.rule, from: x.text, to: x.suggestions[0], why: x.message });
+                    lastStart = x.start;
+                }
+                const punctuation = draftText.slice(p.coreEnd, p.end);
+                let corrected = core + punctuation;
+                const frames = [...d.frames];
+                for (const m of await phrasebook.matchFrames(corrected, o)) {
+                    if (!frames.some((f) => f.id === m.frame.id))
+                        frames.push(await frameOf(m.frame.id));
+                    if (m.changes.length && corrected === core + punctuation) {
+                        corrected = m.text;
+                        for (const c of m.changes)
+                            changes.push({ kind: 'frame', from: c.from, to: c.to, why: `${c.why} (sentence frame “${m.frame.en}”)` });
+                    }
+                }
+                sentences.push({
+                    start: d.start, end: d.end, original: text.slice(d.start, d.end), parts: d.parts,
+                    corrected, changes, hints: hints.reverse(), frames, unchecked: d.unchecked,
+                });
+            }
+            let corrected = '';
+            cursor = 0;
+            for (const s of sentences) {
+                corrected += text.slice(cursor, s.start) + s.corrected;
+                cursor = s.end;
+            }
+            corrected += text.slice(cursor);
+            return { text, corrected, sentences };
+        },
+    };
+}

package/dist/text.d.ts

@@ -0,0 +1,31 @@
+import type { Entry } from './types.ts';
+export declare const UNIT: RegExp;
+export declare const SENTENCE_END: RegExp;
+export type Unit = {
+    text: string;
+    start: number;
+    end: number;
+};
+export type Word = {
+    text: string;
+    lower: string;
+    start: number;
+    end: number;
+    units: Unit[];
+    entries: Entry[];
+};
+export declare function units(text: string): Unit[];
+/** Units grouped into sentences, which end at . ! ? … or a line break. */
+export declare function sentencesOf(text: string, all: Unit[]): Unit[][];
+/** Units join into one word only when just spaces separate them ("thịt heo", not "thịt, heo"). */
+export declare const joined: (text: string, a: Unit, b: Unit) => boolean;
+/**
+ * Longest match against the dictionary: at each position, the longest run of units that's a headword
+ * ("kết quả" is one word, so its "quả" isn't checked on its own). Unknown single units become words with
+ * no entries.
+ */
+export declare function segment(text: string, list: Unit[], maxUnits: number, lookup: (phrase: string) => Promise<Entry[]>): Promise<Word[]>;
+/** Without accents: "không" → "khong", "đi" → "di". */
+export declare const plain: (s: string) => string;
+/** Keeps a capital first letter when replacing a capitalized word ("Tôi" → "Con"). */
+export declare const matchCase: (original: string, replacement: string) => string;