Dictionary
Dictionary looks up English, Chinese, Japanese, and Korean in one window. A result shows the headword, readings, senses, examples, and related words. Favorites, flashcards, handwriting, and an AI fallback sit beside the entry.
Overview
Type a word, pinyin, romaji, or an English meaning. Auto mode picks the language: kana goes to Japanese, and Han text checks the Chinese and Japanese indexes together (a Japanese UI locale wins a tie). You can also pin English, Chinese, Japanese, or Korean from the language control.
Local dictionaries answer first. Wiktionary examples, pronunciation, and extra English glosses fill in afterward. If nothing matches, Ask AI streams a definition into the same entry layout. AI text can be wrong.
The Dashboard dictionary widget uses this same English lookup. The full app adds the other languages, readings, handwriting, cards, favorites, and flashcards.
Features
- Lookup: English, Chinese, Japanese, and Korean, plus compounds and similar words under the entry.
- Readings: pinyin or zhuyin for Chinese, furigana and romaji for Japanese, and romanization for Korean. The Readings menu switches them.
- Chinese character cards: one card per character, using the headword's own characters (豆 in 豆腐 stays 豆). Each card loops a Hanzi Writer stroke-order animation, shows that character's reading and a short CC-CEDICT meaning, and shows the other script when it differs. A neutral-tone syllable uses the character's own reading, so 腐 in 豆腐 is fǔ (decay). Tap the card to look that character up. Tap the stroke box to replay. A missing character stays a static glyph.
- Japanese kanji cards: meanings, on and kun readings, and stroke count from KANJIDIC2. Tap a card to look that character up.
- Handwriting: draw a Chinese character or kanji and pick a candidate. On iOS Safari and the iOS app WebView, the pad turns off text selection and the magnifier loupe while you draw. Definition text in the entry stays selectable.
- Speech: a speaker on the headword, each example, and both sides of a flashcard. A recorded pronunciation plays first. Otherwise the browser voice follows Control Panels when that voice matches the entry language. Japanese is read from kana. Chinese follows the selected script. Cantonese voices are not used for Mandarin.
- Favorites and flashcards: star a word to save it. Cloud Sync copies favorites across devices. Flashcards use SM-2 (Again, Hard, Good, Easy). Space flips a card. Keys 1–4 grade it.
- Ask AI: usage notes stream in while you read. A word the dictionaries miss streams a fallback definition the same way. Synonym chips and example lines appear once each line is finished. A cached note returns as one JSON body.
User Guide
Open Dictionary from the dock or launcher. The welcome state offers sample words. The Chinese sample follows the Readings script. Looking up 豆腐 shows a stroke-order card for each character: 豆 (legume, dòu) and 腐 (decay, fǔ). Tap a card to search that character. Tap the stroke box to replay.
Search from the toolbar. The speaker and star sit on the headword line. Open the handwriting pad to draw, then tap a candidate to add it to the query. Star words you want to study, then switch to flashcards.
Ask AI on an entry for usage notes, or on an empty result for a generated definition. Starting another search cancels the stream in progress.
Data sources and licenses
Each entry lists the sources that produced it. The datasets below are the ones Dictionary ships or calls.
| Source | Used for | License |
|---|---|---|
| WordNet 3.1 | English senses, irregular forms, and synsets | WordNet License. WordNet 3.1 © 2011 Princeton University. All rights reserved |
| CC-CEDICT | Chinese headwords, both scripts, pinyin, and glosses | CC BY-SA 4.0 |
| JMdict | Japanese entries (jmdict-simplified, eng-common) | CC BY-SA 4.0 (EDRDG) |
| KANJIDIC2 | Japanese kanji cards | CC BY-SA 4.0 (EDRDG) |
| kengdic | Korean entries | MPL 2.0 / LGPL 2.0+ |
| Wiktionary | Examples and extra glosses, after the local entry | CC BY-SA 4.0 |
| Free Dictionary API | English pronunciation, audio, and extra examples when WordNet already matched, or the full entry when WordNet has no word | CC BY-SA 3.0 (Wiktionary) |
| Datamuse | Extra English synonyms when it answers in time | Free API |
| hanzi-writer-data 2.0.1 | Stroke order on Chinese character cards, loaded per character from the jsDelivr CDN | Arphic Public License, via Make Me a Hanzi (Arphic Technology) |
| Hanzi Writer | Stroke animation. Loaded only when a Chinese card renders | MIT |
| HanziLookupJS | Handwriting recognition, from /vendor/hanzilookup/ | GNU GPL v3. Stroke file mmah.json is Arphic Public License |
| AI | Usage notes and no-results definitions | Generated. May contain mistakes |
WordNet is fetched as the NLTK wordnet31.zip (same bytes as Princeton's database, under wordnet31/ instead of dict/). Each dataset is tried three times. If the NLTK zip fails, prefetch falls back to Princeton's wn3.1.dict.tar.gz. A cached copy of either archive is reused.
Wiktionary text is stored as plain text. Style blocks and other tags are stripped until the string stops changing, HTML entities are decoded once, and any brackets that decoding reveals are removed.
Technical Details
Window configuration
- Default size: 860 × 580 px
- Minimum size: 420 × 380 px
Endpoints
| Method | Path | Role |
|---|---|---|
| GET | /api/dictionary | q, lang (auto, en, zh, ja, ko), optional locale. Returns the local entry. enrichmentPending is set while Wiktionary is still loading |
| GET | /api/dictionary/enrich | Same query after Wiktionary examples are merged. Skipped when the local entry already has an example |
| POST | /api/dictionary/ai | { word, lang, mode: "fallback" or "extras", locale? }. Streams text (text/event-stream, Cache-Control: no-cache, no-transform, Content-Encoding: identity, X-Accel-Buffering: no). A Redis hit is JSON |
Lookup is limited to 90 requests per minute per IP and is available without an account. AI keeps its own auth and rate limits.
Indexes and caching
The API loads English, Chinese, Japanese, Korean, and kanji indexes at startup. The Docker image downloads the datasets into /app/data/dictionary, then bun scripts/build-dictionary-indexes.ts writes gzipped snapshots (index-zh.rydx and the same for ja, ko, and en, plus kanji.json.gz). Boot reads the snapshots. If a snapshot is missing, the server parses the raw file on first use.
Compound lists and longest-match segmentation use a sorted prefix index, and a suffix array for phrases that contain the word. Auto mode builds the Chinese and Japanese checks together.
Redis keeps a remote hit for 30 days, a confirmed miss for 1 day, and a timeout or server error for 5 minutes. The finished lookup is cached for 30 days, or 6 hours when nothing matched. AI notes and fallback definitions are cached for 30 days, and only after the stream finishes. A disconnect aborts the model call and does not cache a partial note.
Browsers may cache a found word for a day (max-age=86400) and reuse it for a week while refreshing (stale-while-revalidate=604800). The window keeps the last 80 lookups in memory. Typing cancels the previous request.
Duplicate headwords are merged (NFC, trimmed, and the same hanja, traditional form, or reading when both sides have one). Chinese rows with different traditional forms stay separate (干 and 乾). The richer row supplies the glosses. Homographs with different hanja or readings stay separate. Cache reads run the same merge, so an older Redis payload does not bring a duplicate back. Lookup keys include parser version v6, so a payload written by an older parser is not reused.
Chinese character cards mount after a fallback AI stream finishes. Writer methods run only after stroke data loads, and a failed load keeps the static glyph. An error boundary around the cards section does the same if one card throws.
Components
src/apps/dictionary/components/DictionaryAppComponent.tsx– window shell
src/apps/dictionary/components/DictionaryMenuBar.tsx– menus, including Readingssrc/apps/dictionary/components/DictionaryToolbar.tsx– searchsrc/apps/dictionary/components/DictionaryEntryView.tsx– senses, phrases, and the source footersrc/apps/dictionary/components/DictionaryHanziCards.tsx– stroke-order cards. The stroke box replays; the rest of the card looks the character upsrc/apps/dictionary/components/DictionaryKanjiCards.tsx– kanji cards. The whole card looks the character upsrc/apps/dictionary/components/DictionaryHandwritingPad.tsx– drawing padsrc/apps/dictionary/components/DictionaryFlashcardsView.tsx– SM-2 reviewsrc/apps/dictionary/components/DictionarySpeakButton.tsx– recorded audio, then browser speechsrc/apps/dictionary/hooks/useDictionaryLogic.ts– lookup, enrichment, and AI streamingsrc/apps/dictionary/utils/hanziStrokeData.ts– per-character[email protected]fetchsrc/shared/dictionary.ts– shared entry types andDICTIONARY_SOURCE_INFOapi/dictionary/index.ts,api/dictionary/enrich.ts,api/dictionary/ai.ts– HTTP handlers
Related Apps
- Dashboard – the dictionary widget calls the same English lookup
- Control Panels – the Sound voice is preferred when it speaks the entry language