which-dialect 0.1.0

package/dist/translate.d.ts

@@ -0,0 +1,153 @@
+import { type Example, type Hit, type PronounChoice, type PronounPerson, type TableTranslation } from './types.ts';
+import { type Dictionary, type LoadJson } from './index.ts';
+/** One meaning of the source word, with its own part of speech and definitions. */
+export type SourceSense = {
+    /** The word as given. */
+    word: string;
+    /** The word this sense belongs to: the base form or standard spelling ("say" for "said", "không" for "hông"). */
+    lemma: string;
+    pos: string;
+    /** English definitions of this sense. */
+    glosses: string[];
+    regions: string[];
+    regionTagged: boolean;
+    labels: string[];
+    /** How `word` leads to `lemma` when they differ, e.g. "simple past of say" or "Southern Vietnam form of không". */
+    via?: string;
+    /** Same-language words with this meaning (often other dialects' words). */
+    synonyms?: string[];
+    /** Example sentences for this meaning. */
+    examples?: Example[];
+    /** English senses only: Wiktionary's translation table for this meaning (see Sense.translations). */
+    translations?: Record<string, TableTranslation[]>;
+};
+/** A target-language word for a source sense. */
+export type Translation = Hit & {
+    /** Higher is better. Comparable within one group. */
+    score: number;
+    /**
+     * How this word was found: the English term that linked it, "synonym" for a same-language synonym,
+     * "table" for Wiktionary's translation table, or "pronouns" for a pronoun-table row's words (the
+     * `listener`'s or `about`'s row, or the default row).
+     */
+    bridge: string;
+    /** Example sentences for this word in the matched sense, when the dictionary has them. */
+    examples?: Example[];
+    /** For pronoun-table words: the relationship it's for, e.g. "Your parents". */
+    relationship?: string;
+};
+/**
+ * A relationship the source word is used in as "I", "you", "he/she", "we", plural "you" or "they", from the
+ * source language's pronoun table (Vietnamese "em": I, talking to someone a bit older; you, talking to
+ * someone younger).
+ */
+export type PronounUse = {
+    /** Row id, e.g. "older-male". */
+    id: string;
+    /** Who you're talking to (or about), e.g. "Someone a bit older (man)". */
+    label: string;
+    /** The table column: 'self' ("I"), 'addressee' ("you"), 'third' ("he/she"), or their plurals. */
+    person: PronounPerson;
+    /** Only said by a male or female speaker. */
+    speaker?: 'male' | 'female';
+    /** The gender of the person the word refers to, when it has one. */
+    gender?: 'male' | 'female';
+    regions: string[];
+    regionTagged: boolean;
+    note?: string;
+    warning?: string;
+};
+/** The words for one person ("I", "you", "he"…) in one relationship, from the target's pronoun table. */
+export type RelationshipWords = {
+    /** Row id, usable as `listener` (I/you/we) or `about` (he/she/they). */
+    id: string;
+    /** Who you're talking to, e.g. "Your parents". */
+    label: string;
+    words: PronounChoice[];
+    warning?: string;
+};
+export type TranslationGroup = {
+    source: SourceSense;
+    /** English terms used to bridge this sense, main meaning first. */
+    bridge: string[];
+    /** Best first. */
+    translations: Translation[];
+    /**
+     * For personal-pronoun senses ("I", "you", "he/she", "we", "they"), when the target language has a
+     * pronoun table (Vietnamese): the word to use for each relationship, filtered by `toRegion`, `speaker`,
+     * `exclude`, and the pronoun's gender (he/she) or inclusiveness (we). Pass one's `id` as `listener`
+     * (I/you/we) or `about` (he/she/they) to put its words first.
+     */
+    relationships?: RelationshipWords[];
+    /**
+     * When the source word is in the source language's pronoun table: the relationships it's used in with
+     * this meaning. Uses no definition covers get a group of their own, translated as "I", "you", "he"…
+     * (Vietnamese "em" is only defined as "younger sibling" and "refers to any person described by em").
+     */
+    pronounUses?: PronounUse[];
+};
+export type TranslateOptions = {
+    /** Source language code, e.g. "vi". */
+    from: string;
+    /** Target language code, e.g. "en". Can equal `from` to translate between dialects of one language. */
+    to: string;
+    /** Region or region group the source word is from, e.g. "Northern". Keeps only senses used there. */
+    fromRegion?: string;
+    /** Region or region group to translate into, e.g. "Southern". Words tagged for it rank first. */
+    toRegion?: string;
+    /** Only source senses with this part of speech. */
+    pos?: string;
+    /** Words describing the meaning you want, e.g. "awesome" for "cool". Matching senses and words rank first. */
+    meaning?: string;
+    /**
+     * The register you want translations in, instead of the source sense's own: 'casual' prefers
+     * colloquial words (Southern "tui" for "I"), 'polite' polite/formal ones, 'neutral' plain ones.
+     */
+    register?: 'casual' | 'neutral' | 'polite';
+    /**
+     * Who you're talking to, as a pronoun-table row id of the target language (e.g. Vietnamese "parent",
+     * "older-male", "friend"; see Dictionary.pronouns). For "I", "you", "we" and plural "you", that
+     * relationship's words come first. Without it, the table's default row's words do (Vietnamese "tôi",
+     * "bạn"). Ignored for targets without a pronoun table; unknown ids throw, listing the valid ones.
+     */
+    listener?: string;
+    /** Who you're talking about, as a row id like `listener`: for "he", "she", "him", "her", "they", "them". */
+    about?: string;
+    /** The speaker's gender, for pronoun-table words that depend on it ("anh" vs "chị" toward someone younger). */
+    speaker?: 'male' | 'female';
+    /** Labels to leave out of translations (default DEFAULT_EXCLUDED_LABELS). */
+    exclude?: string[];
+    /** Maximum translations per source sense (default 5). */
+    limit?: number;
+    /**
+     * Return every sense, including ones with no translation (empty `translations`) and ones whose
+     * translations repeat another sense's. Default false. Useful for letting users pick a meaning.
+     */
+    allSenses?: boolean;
+};
+export type Translator = {
+    /** The senses of a word, following forms and variant spellings to the words they belong to. */
+    senses(word: string, options: {
+        from: string;
+        fromRegion?: string;
+        pos?: string;
+    }): Promise<SourceSense[]>;
+    /** Translations grouped by source sense, most relevant sense first. */
+    translate(word: string, options: TranslateOptions): Promise<TranslationGroup[]>;
+};
+export type TranslatorOptions = {
+    /** Returns the dictionary for a language. Defaults to createDictionary with the options below. */
+    dictionary?: (lang: string) => Dictionary;
+    /** Where each language's data is served (see DictionaryOptions.baseUrl). */
+    baseUrl?: (lang: string) => string;
+    /** Custom loader per language (see DictionaryOptions.load). */
+    load?: (lang: string) => LoadJson;
+};
+/**
+ * Possible base words for a regularly inflected English word, most likely first: "walked" -> walk,
+ * "cities" -> city, "making" -> make, "stopped" -> stop. The English data package only stores irregular
+ * forms ("said", "went"), so regular ones are undone here.
+ */
+export declare function regularBaseForms(word: string): string[];
+export declare const FREQUENCY_WEIGHT = 1.2;
+export declare function createTranslator(options?: TranslatorOptions): Translator;