Module languagesupport
Language-specific handling module.
This module defines a somewhat generic system by which language-specific plugins can improve KOReader's support for languages that are not close enough to European languages to "just work".
This was originally designed to improve KoReader's Japanese support through the Japanese plugin (plugins/japanese.koplugin) but it should be generic enough for other language plugins to build off this framework. Examples of languages which may require such a plugin include highly inflected/agglutinative languages (Japanese and Korean) and languages where spaces are not used as a delimiting character between words (Japanese and Chinese) and languages that use a character set where KoReader's dependencies define a "word" as being a single character.
This module works by providing a mechanism to define a series of callbacks (not unlike UI Events) which are called during operations where language-specific knowledge may be necessary (such as during text selection and dictionary lookup of a text fragment).
Functions
| LanguageSupport:registerPlugin (Plugin) | Registers a new language-specific plugin with given language_code. |
| LanguageSupport:hasActiveLanguagePlugins () | Returns whether there are any language plugins currently enabled. |
| LanguageSupport:improveWordSelection (selection) | Called from ReaderHighlight:onHold after the document-specific handler has successfully grabbed a "word" from the document. |
| LanguageSupport:extraDictionaryFormCandidates (text) | Called from ReaderHighlight:startSdcv after the selected has text has been OCR'd, cleaned, and otherwise made ready for sdcv. |
Functions
- LanguageSupport:registerPlugin (Plugin)
-
Registers a new language-specific plugin with given language_code.
If a plugin using the same language code already exists, the loading is skipped. The language code is used to prioritise which language plugin should be called first (if that plugin fails to handle the text, there is no such plugin, or the document has no language defined then all of the plugins are called one-by-one until one succeeds).
The follow handlers are defined (if you wish to support the handler create the corresponding onHandler method):
- WordSelection (onWordSelection) is called when a highlight is first created and can be used to modify the default "word boundary" word selection to match user expectations.
Note that "XPointer" is used here but code written should take it as an opaque object and only use the given callbacks since in future this feature may work with PDFs and all of the XPointers will instead be PDF equivalents.
Called with {
pos0 = [XPointer], pos1 = [XPointer], callbacks = { -- Equivalent to document:getPrevVisibleChar(pos). get_prev_char_pos(pos: XPointer) -> XPointer, -- Equivalent to document:getNextVisibleChar(pos). get_next_char_pos(pos: XPointer) -> XPointer, -- Equivalent to document:getTextFromXPointers(pos0, pos1). get_text_in_range(pos0: XPointer, pos1: XPointer) -> string, }} table as the only argument.
Must return the new (pos0, pos1) XPointers or nil if the word couldn't be expanded.
- WordLookup (onWordLookup) is called when a dictionary lookup is triggered on some text and can be used to adjust the word such that it is in the dictionary form and can be found in the dictionary. This is primarily useful for languages where StarDict "fuzzy searching" is not usable.
Called with
{ text = [string] }table as the only argument.
Must return an array of candidate words (in decreasing order of preference) which will be looked up or nil if no candidate words could be generated. Note that if more than one candidate is found in the dictionary they will all be displayed to the user. It is not necessary to include the original word in the candidate list -- it will always be given highest priority.
Parameters:
- Plugin to register (plugin.name is used as the internal name and must not be nil or "").
Returns:
-
bool
Whether the plugin was successfully registered.
- LanguageSupport:hasActiveLanguagePlugins ()
-
Returns whether there are any language plugins currently enabled.
Returns:
-
bool
whether there are any registered plugins
- LanguageSupport:improveWordSelection (selection)
-
Called from ReaderHighlight:onHold after the document-specific handler has
successfully grabbed a "word" from the document. If the selection is to
updated, improveWordSelection will also update the document's internal
selection state (for crengine) to correctly display the right selection.
Parameters:
- selection Text selection table to improve if possible.
Returns:
-
New updated selected_text table which should be used (or nil).
- LanguageSupport:extraDictionaryFormCandidates (text)
-
Called from ReaderHighlight:startSdcv after the selected has text has been
OCR'd, cleaned, and otherwise made ready for sdcv.
Parameters:
- text string Original text being searched by the user.
Returns:
-
{string,...}
Extra dictionary form candidates to search (or nil).