alex/yomichan
1
Fork 0
Code Releases Activity

Add mode documentation about the types used by Translator (#2147)

Browse Source
This commit is contained in:
toasted-nutbread 2022-05-19 20:16:40 -04:00 committed by GitHub
parent 6e239638bb
commit ae0ad227c0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 203 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
docs/interfaces/translator-types.ts Normal file
View File

@ -0,0 +1,177 @@
/*
* Copyright (C) 2022 Yomichan Authors
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
namespace Translation {
// Kanji
/**
* An options object for use with `Translator.findKanji`.
*/
export interface FindKanjiOptions {
/**
* The mapping of dictionaries to search for kanji in.
* The key is the dictionary name.
*/
enabledDictionaryMap: Map<string, FindKanjiDictionary>;
}
/**
* Details about a dictionary.
*/
export interface FindKanjiDictionary {
/**
* The index of the dictionary
*/
index: number;
/**
* The priority of the dictionary
*/
priority: number;
}
// Terms
/**
* An options object for use with `Translator.findTerms`.
*/
export interface FindTermsOptions {
/**
* The matching type for looking up terms.
*/
matchType: FindTermsMatchType;
/**
* The name of the primary dictionary to search.
*/
mainDictionary: string;
/**
* The name of the frequency dictionary used for sorting
*/
sortFrequencyDictionary: string | null;
/**
* The order used when using a sorting dictionary.
*/
sortFrequencyDictionaryOrder: FindTermsSortOrder;
/**
* Whether or not non-Japanese characters should be searched.
*/
removeNonJapaneseCharacters: boolean;
/**
* Whether or not half-width characters should be converted to full-width characters.
*/
convertHalfWidthCharacters: FindTermsVariantMode;
/**
* Whether or not ASCII numeric characters should be converted to full-width numeric characters.
*/
convertNumericCharacters: FindTermsVariantMode;
/**
* Whether or not alphabetic characters should be converted to kana.
*/
convertAlphabeticCharacters: FindTermsVariantMode;
/**
* Whether or not hiragana characters should be converted to katakana.
*/
convertHiraganaToKatakana: FindTermsVariantMode;
/**
* Whether or not katakana characters should be converted to hiragana.
*/
convertKatakanaToHiragana: FindTermsVariantMode;
/**
* How emphatic character sequences should be collapsed.
*/
collapseEmphaticSequences: FindTermsEmphaticSequencesMode;
/**
* An iterable sequence of text replacements to be applied during the term lookup process.
*/
textReplacements: Iterable<(FindTermsTextReplacement | null)> | null;
/**
* The mapping of dictionaries to search for terms in.
* The key is the dictionary name.
*/
enabledDictionaryMap: Map<string, FindTermDictionary>;
/**
* A set of dictionary names which should have definitions removed.
*/
excludeDictionaryDefinitions: Set<string> | null;
}
/**
* The matching type for looking up terms.
*/
export enum FindTermsMatchType {
Exact = 'exact',
Prefix = 'prefix',
Suffix = 'suffix',
}
/**
* A sorting order to use when finding terms.
*/
export enum FindTermsSortOrder {
Ascending = 'ascending',
Descending = 'descending',
}
/**
* Mode describing how to handle variations.
*/
export enum FindTermsVariantMode {
False = 'false',
True = 'true',
Variant = 'variant',
}
/**
* Mode describing how to handle emphatic sequence variations.
*/
export enum FindTermsEmphaticSequencesMode {
False = 'false',
True = 'true',
Full = 'full',
}
/**
* Information about how text should be replaced when looking up terms.
*/
export interface FindTermsTextReplacement {
/**
* The pattern to replace.
*/
pattern: RegExp;
/**
* The replacement string. This can contain special sequences, such as `$&`.
*/
replacement: string;
}
/**
* Details about a dictionary.
*/
export interface FindTermDictionary {
/**
* The index of the dictionary
*/
index: number;
/**
* The priority of the dictionary
*/
priority: number;
/**
* Whether or not secondary term searches are allowed for this dictionary.
*/
allowSecondarySearches: boolean;
}
}

12
ext/js/background/backend.js
View File

@ -1958,6 +1958,13 @@ class Backend {
this._applyOptions(source);
}
/**
* Creates an options object for use with `Translator.findTerms`.
* @param {string} mode The display mode for the dictionary entries.
* @param {{matchType: string, deinflect: boolean}} details Custom info for finding terms.
* @param {object} options The options.
* @returns {FindTermsOptions} An options object.
*/
_getTranslatorFindTermsOptions(mode, details, options) {
let {matchType, deinflect} = details;
if (typeof matchType !== 'string') { matchType = 'exact'; }
@ -2006,6 +2013,11 @@ class Backend {
};
}
/**
* Creates an options object for use with `Translator.findKanji`.
* @param {object} options The options.
* @returns {FindKanjiOptions} An options object.
*/
_getTranslatorFindKanjiOptions(options) {
const enabledDictionaryMap = this._getTranslatorEnabledDictionaryMap(options);
return {enabledDictionaryMap};

68
ext/js/language/translator.js
View File

@ -27,8 +27,9 @@
class Translator {
/**
* Creates a new Translator instance.
* @param japaneseUtil An instance of JapaneseUtil.
* @param database An instance of DictionaryDatabase.
* @param {object} details The details for the class.
* @param {JapaneseUtil} details.japaneseUtil An instance of JapaneseUtil.
* @param {DictionaryDatabase} details.database An instance of DictionaryDatabase.
*/
constructor({japaneseUtil, database}) {
this._japaneseUtil = japaneseUtil;
@ -42,7 +43,7 @@ class Translator {
/**
* Initializes the instance for use. The public API should not be used until
* this function has been called.
* @param deinflectionReasons The raw deinflections reasons data that the Deinflector uses.
* @param {object} deinflectionReasons The raw deinflections reasons data that the Deinflector uses.
*/
prepare(deinflectionReasons) {
this._deinflector = new Deinflector(deinflectionReasons);
@ -57,42 +58,11 @@ class Translator {
/**
* Finds term definitions for the given text.
* @param mode The mode to use for finding terms, which determines the format of the resulting array.
* @param {string} mode The mode to use for finding terms, which determines the format of the resulting array.
* One of: 'group', 'merge', 'split', 'simple'
* @param text The text to find terms for.
* @param options An object using the following structure:
* ```
* {
* matchType: (enum: 'exact', 'prefix', 'suffix'),
* mainDictionary: (string),
* sortFrequencyDictionary: (null or string),
* sortFrequencyDictionaryOrder: (enum: 'ascending', 'descending'),
* removeNonJapaneseCharacters: (boolean),
* convertHalfWidthCharacters: (enum: 'false', 'true', 'variant'),
* convertNumericCharacters: (enum: 'false', 'true', 'variant'),
* convertAlphabeticCharacters: (enum: 'false', 'true', 'variant'),
* convertHiraganaToKatakana: (enum: 'false', 'true', 'variant'),
* convertKatakanaToHiragana: (enum: 'false', 'true', 'variant'),
* collapseEmphaticSequences: (enum: 'false', 'true', 'full'),
* textReplacements: [
* (null or [
* {pattern: (RegExp), replacement: (string)}
* ...
* ])
* ...
* ],
* enabledDictionaryMap: (Map of [
* (string),
* {
* index: (number),
* priority: (number),
* allowSecondarySearches: (boolean)
* }
* ]),
* excludeDictionaryDefinitions: (Set of (string) or null)
* }
* ```
* @returns An object of the structure `{dictionaryEntries, originalTextLength}`.
* @param {string} text The text to find terms for.
* @param {Translation.FindTermsOptions} options A object describing settings about the lookup.
* @returns {{dictionaryEntries: Translation.TermDictionaryEntry[], originalTextLength: number}} An object containing dictionary entries and the length of the original source text.
*/
async findTerms(mode, text, options) {
const {enabledDictionaryMap, excludeDictionaryDefinitions, sortFrequencyDictionary, sortFrequencyDictionaryOrder} = options;
@ -136,20 +106,11 @@ class Translator {
/**
* Finds kanji definitions for the given text.
* @param text The text to find kanji definitions for. This string can be of any length,
* @param {string} text The text to find kanji definitions for. This string can be of any length,
* but is typically just one character, which is a single kanji. If the string is multiple
* characters long, each character will be searched in the database.
* @param options An object using the following structure:
* {
* enabledDictionaryMap: (Map of [
* (string),
* {
* index: (number),
* priority: (number)
* }
* ])
* }
* @returns An array of definitions. See the _createKanjiDefinition() function for structure details.
* @param {Translation.FindKanjiOptions} options A object describing settings about the lookup.
* @returns {Translation.KanjiDictionaryEntry[]} An array of definitions. See the _createKanjiDefinition() function for structure details.
*/
async findKanji(text, options) {
const {enabledDictionaryMap} = options;
@ -185,11 +146,10 @@ class Translator {
/**
* Gets a list of frequency information for a given list of term-reading pairs
* and a list of dictionaries.
* @param termReadingList An array of `{term, reading}` pairs. If reading is null,
* @param {{term: string, reading: string|null}[]} termReadingList An array of `{term, reading}` pairs. If reading is null,
* the reading won't be compared.
* @param dictionaries An array of dictionary names.
* @returns An array of objects with the format
* `{term, reading, dictionary, hasReading, frequency}`.
* @param {Iterable<string>} dictionaries An array of dictionary names.
* @returns {TermFrequency[]} An array of term frequencies.
*/
async getTermFrequencies(termReadingList, dictionaries) {
const dictionarySet = new Set();