Skip to content

dictionary.md

Latest commit

 

History

History
98 lines (66 loc) · 9.15 KB

dictionary.md

File metadata and controls

98 lines (66 loc) · 9.15 KB
Raw

Dictionary

Look up words and phrases while reading an EPUB using an offline StarDict dictionary stored on the SD card.

Japanese and Chinese books do not use StarDict: they read converted files from /dictionaries/jp/ (Japanese), /dictionaries/zh/ (Mandarin, simplified and traditional) and /dictionaries/yue/ (Cantonese), because their text has no word spaces and the lookup segments the page by dictionary word. See dictionary-setup.md for the files and converter commands; everything below is about the other languages.

Supported Format

The reader supports StarDict dictionaries. When searching for dictionaries online, look for "StarDict format" or files with .dict, .idx, and .ifo extensions.

A dictionary folder must contain:

  • .idx — word index (required, must be uncompressed — a .idx.gz will not work; decompress it on your computer with gzip -d first)
  • .dict or .dict.dz — definition data (.dict.dz is supported as-is; entries are decompressed on the fly during lookup)
  • .syn — synonym index (optional; maps alternate spellings and irregular forms to their headword)
  • .ifo — metadata (optional)

Not supported: dictionaries with 64-bit index offsets (idxoffsetbits=64 in the .ifo — rare, and rejected with an error).

Note

If you use .dict.dz and Crosspoint failed to load your dictionary with error message "Not enough memory", try unzipping it.

Setting Up a Dictionary

  1. Copy your dictionary folder(s) to /dictionaries/ on the SD card — one dictionary per folder, e.g. /dictionaries/webster/webster.idx + webster.dict.dz. A hidden /.dictionaries/ folder (dot-prefixed) works the same way, for keeping it out of the file browser.
  2. Open Settings → Reader → Fallback dictionary on the device.
  3. Select the dictionary to use when a book's language has no matching dictionary, or None to disable fallback lookups. For a tagged EPUB with matching language folders, those dictionaries are used automatically: up to four in one language (/dictionaries/en/collins/, /dictionaries/en/wiktionary/) are all checked, and every entry found is shown in one run of pages, with the dictionary picked here first if it is one of them and the rest by folder name. The Reader Settings Dictionary row shows the dictionary a book reads first and is read-only.

The Fallback dictionary row only appears when at least one usable dictionary folder exists. Folders containing more than one dictionary (multiple .idx stems) are skipped as ambiguous.

Looking Up Words and Phrases

Three ways to start a lookup while reading:

  • Long-press a word on the screen (touch devices). The definition opens straight away, with no setting to turn on first. A press that lands between words opens ordinary word selection instead, so the gesture is never a dead end. Closing a definition opened this way returns to the page.
  • Open the reader menu (Confirm) and choose Look Up.
  • Or set Settings → Controls → Long-press Menu to "Dictionary", then hold Confirm (~0.4s) on the reading page.

Selecting Text

On button-driven devices:

  1. A selection cursor appears on a word. Use Left/Right to navigate between words in reading order, and the side Up/Down buttons to jump between lines or flip across nearby pages.
  2. Press Confirm (Select) to anchor the start of the selection.
  3. Single word: Press Confirm again immediately (Look Up) to look up the highlighted word.
  4. Phrase / multiple words: Use Left/Right or Up/Down to extend the highlighted selection across words, lines, or pages. Then press Confirm (Look Up).
  5. Press Back at any time to cancel and return to reading.

On touchscreen devices:

  • Tap or drag the selection handles across words to highlight a word or phrase, then tap Look Up.

On the very first lookup with a dictionary (and again whenever the .idx or .syn source file changes), the reader shows "Indexing dictionary…" while it builds small sidecar files next to them — a .qidx for the word index, and a .sidx when a .syn synonym file is present. Each sidecar is rebuilt independently, only when its own source changes. This takes a few seconds for large dictionaries and makes all subsequent lookups fast. The sidecars can be deleted safely at any time — they will simply be rebuilt.

How Lookup Works

  1. Direct match — the word or phrase is searched as-is (case-insensitive) in the dictionary index. Leading and trailing punctuation and whitespace are stripped automatically. Multi-word phrases match dictionary entries containing spaces (such as idioms, phrasal verbs, or compound terms).
  2. Synonyms — on a miss, if the dictionary ships a .syn file, alternate spellings and irregular forms recorded there are resolved to their headword (e.g. oxen → ox, colour → color). This step is skipped if the .sidx sidecar could not be built (e.g. transient low memory during indexing); the dictionary otherwise stays usable, and the build is retried the next time it is opened.
  3. Inflection — still no match: word forms are retried automatically, using the rules for the book's language.
    • Accented capitals are folded first, in every language, so a word at the start of a sentence (École, Être, Über) reaches its lowercase headword.
    • English, and any language without its own rules: possessives and plurals (dogs → dog, stories → story) and verb endings (walked → walk, running → run, making → make).
    • French: elision (l'eau → eau, qu'il → il), plurals and feminines (journaux → journal, heureuse → heureux, nouvelle → nouveau), the three regular conjugations across their tenses (parlaient → parler, mangeons → manger, finissent → finir, vendu → vendre), the stem-alternating families built on them (éteignit → éteindre, connaissons → connaître, conduisit → conduire), and adjective → adverb (lentement → lent).
  4. Not found — a short popup appears and you return to word selection.

The rules are selected by the book's language tag, falling back to the language folder the dictionary sits in (/dictionaries/fr/...) for a book with no tag. They cover regular morphology only: irregular verbs that share no stem with their lemma (French est, ont, fut, vais), and a verb's irregular passé simple (French connus, naquit), are not rule-reachable and need a .syn, which resolves them in one step and works in any language.

The Definition Screen

When a word is found, the definition screen shows the matched headword at the top and the definition text below, with a page counter for long definitions.

HTML dictionaries (sametypesequence=h) and XDXF dictionaries (sametypesequence=x) use the EPUB text-layout engine for supported formatting such as headings, bold, italics, lists, and line breaks. Unrecognized tags keep their text without special formatting. Images and CSS styling are ignored. Definitions that are too large or cannot be parsed or laid out within the available memory fall back to plain text.

  • Left/Right or side Up/Down — previous / next page
  • Back — return to word selection
  • Touch — the card pages the same way the reader itself is set to turn pages (Settings → Controls → Touch Reader Controls): tap zones, inverted zones, swipes, inverted swipes, or nothing at all when touch page turns are off. A tap outside the card puts it away.

Where to find dictionaries

credit to https://github.com/koreader/koreader/wiki/Dictionary-support for the list.