opendict-rs

A Rust library for reading StarDict and MDict dictionary files through a unified API.

Quick start

use opendict::{open, Dictionary};

// Auto-detects format from directory contents
let dict = open("path/to/dictionary-dir")?;

println!("{}", dict.info().name);            // dictionary title
println!("{}", dict.word_count());           // number of entries

if let Some(entries) = dict.lookup("hello")? {
    for entry in entries {
        println!("{}", String::from_utf8_lossy(&entry.data));
    }
}

let matches = dict.search_prefix("hel", 10); // prefix search
let words = dict.word_list();                 // all headwords

Format-specific APIs

use opendict::stardict::StarDictDictionary;
use opendict::mdict::MdictDictionary;

// StarDict — synonyms
let sd = StarDictDictionary::open_dir("path/to/stardict-dir".as_ref())?;
if let Some(entries) = sd.lookup_synonym("hi")? {
    // resolves synonym → target word → entries
}

// MDict — resource files (.mdd)
let md = MdictDictionary::open("path/to/mdict-dir".as_ref())?;
let css = md.lookup_resource("\\style.css");  // CSS, images, fonts

Format support

StarDict

MDict

Both formats

• Memory-mapped I/O for dictionary data
• Binary search with prefix search
• Single-entry block cache to avoid redundant decompression (MDict)
• Optional disk caching of .dict.dz/.idx.gz decompression (StarDict)

Bindings

Node.js

Native addon via napi-rs. Auto-detects dictionary format.

import { Dictionary } from '@opendict-rs/node'

const dict = new Dictionary('/path/to/dictionary-dir')

console.log(dict.info.name)
console.log(dict.wordCount())

const entries = dict.lookup('hello')
if (entries) {
  console.log(entries[0].data)
}

const matches = dict.searchPrefix('hel', 10)

Build from source:

cd node && npm install && npm run build

Expo (React Native)

Native module via uniffi + Expo Modules. Supports iOS and Android.

import { Dictionary } from '@opendict-rs/expo'

const dict = new Dictionary('/path/to/dictionary-dir')

console.log(dict.info.name)
console.log(dict.wordCount())

const entries = dict.lookup('hello')
const matches = dict.searchPrefix('hel', 10)

dict.close() // free native resources when done

Requires cross-compiling the Rust library for your target platform. See examples/expo-test for a complete example app.

Performance

Release mode, benchmarked against real dictionaries.

Load time

Lookup (sequential, all words)

Prefix search runs in 1-4 us across all dictionaries.

MDict mmap vs Vec on the Oxford OED (277k words, ~230 MB .mdx): RSS dropped from 234 MB to 24 MB (-90%), load time from 101 ms to 64 ms (-37%).

Tests

cargo test                      # unit + integration tests
cargo test -- --ignored         # + real dictionary tests (requires files in tests/dicts/)
cargo bench                     # criterion benchmarks (set OPENDICT_BENCH_DIR)

Dependencies

flate2 = "1"          # zlib decompression
memmap2 = "0.9"       # memory-mapped I/O
encoding_rs = "0.8"   # character encoding (GBK, Big5, etc.)
adler2 = "2"          # adler32 checksums
lzo1x = "0.2"         # LZO decompression
xxhash-rust = "0.8"   # v3 key derivation
log = "0.4"           # optional warning logs

Contributing

Contributions are very welcome — bug fixes, performance improvements, docs, tests, additional fixtures, all of it.

The biggest gap is support for more dictionary formats (Lingoes, DSL, Babylon BGL, XDXF, plain text). I'd like opendict-rs to grow into a genuinely format-agnostic reader, but I'm unlikely to get to those any time soon — if you need one, opening a PR is the fastest way to make it happen. The existing StarDict and MDict modules under src/ are good templates for how a new format slots in behind the Dictionary trait.

See CONTRIBUTING.md for the repo layout, build steps for each binding (Rust core, Node, Expo), and the rule for keeping the bindings thin.

Acknowledgements

The MDict implementation was built with reference to:

• mdict-analysis — Xiaoqiang Wang's Python analysis of the MDict format
• mdict — Jeka Kiselyov's JavaScript MDict reader
• writemdict — Zhanshi Liu's Python MDict writer (useful for understanding the binary format)

License

MIT