Compiling Dictionaries

This guide shows how to compile ODXML into .odict binary files programmatically. For CLI usage, see the Quick Start.

Compiling from an XML string

The simplest approach is to compile an XML string directly into an in-memory dictionary.

Rust

use odict::{OpenDictionary, ToDictionary};

fn main() -> odict::Result<()> {
  let xml = r#"

  <dictionary name="My Dictionary">
    <entry term="hello">
      <ety>
        <sense pos="intj">
          <definition value="A greeting" />
        </sense>
      </ety>
    </entry>
  </dictionary>
  "#;

  // Parse XML → build binary → get OpenDictionary
  let dict = xml.to_dictionary()?.build()?;

  // Write to disk
  dict.to_disk("my-dictionary.odict")?;

  Ok(())
}

Python

from theopendictionary import OpenDictionary, compile

xml = """
<dictionary name="My Dictionary">
  <entry term="hello">
    <ety>
      <sense pos="intj">
        <definition value="A greeting" />
      </sense>
    </ety>
  </entry>
</dictionary>
"""

# Option 1: compile() returns raw bytes
compiled_bytes = compile(xml)
dictionary = OpenDictionary(compiled_bytes)

# Option 2: pass XML directly to the constructor
dictionary = OpenDictionary(xml)

# Save to disk
dictionary.save("my-dictionary.odict")

JavaScript

import { compile, OpenDictionary } from "@odict/node";

const xml = `

<dictionary name="My Dictionary">
  <entry term="hello">
    <ety>
      <sense pos="intj">
        <definition value="A greeting" />
      </sense>
    </ety>
  </entry>
</dictionary>
`;

// Option 1: compile() returns a Buffer
const data = compile(xml);
const dictionary = new OpenDictionary(data);

// Option 2: pass XML directly to the constructor
const dictionary = new OpenDictionary(xml);

// Save to disk
dictionary.save("my-dictionary.odict");

Compiling from an XML file

If your XML lives on disk, read it first and then compile.

Rust

use odict::schema::Dictionary;

fn main() -> odict::Result<()> {
    let dict = Dictionary::from_path("my-dictionary.xml")?
        .build()?;

    dict.to_disk("my-dictionary.odict")?;

    Ok(())
}

Python

from theopendictionary import OpenDictionary, compile

with open("my-dictionary.xml", "r") as f:
xml = f.read()

compiled_bytes = compile(xml)
dictionary = OpenDictionary(compiled_bytes)
dictionary.save("my-dictionary.odict")

JavaScript

import { readFile } from "node:fs/promises";
import { compile, OpenDictionary } from "@odict/node";

const xml = await readFile("my-dictionary.xml", "utf-8");
const data = compile(xml);
const dictionary = new OpenDictionary(data);

dictionary.save("my-dictionary.odict");

Compression options

ODict uses Brotli compression. You can configure the compression level when saving.

Rust

use odict::{compile::CompilerOptions, CompressOptions, ToDictionary};

fn main() -> odict::Result<()> {
  let xml = std::fs::read_to_string("my-dictionary.xml")?;

  let compress = CompressOptions::default()
      .quality(11)
      .window_size(22);

  let options = CompilerOptions::default()
      .with_compression(compress);

  xml.as_str()
      .to_dictionary()?
      .build()?
      .to_disk_with_options("my-dictionary.odict", options)?;

  Ok(())
}

Python

dictionary.save(
    "my-dictionary.odict",
    quality=11,       # Maximum compression (0–11)
    window_size=22    # Window size (0–22)
)

JavaScript

dictionary.save("my-dictionary.odict", {
  compress: {
    quality: 11, // Maximum compression (0–11)
    windowSize: 22, // Window size (0–22)
  },
});

Loading compiled dictionaries

Once compiled, you can load .odict files from disk or from the remote registry.

Rust

use odict::OpenDictionary;

fn main() -> odict::Result<()> {
  let file = OpenDictionary::from_path("my-dictionary.odict")?;
  let dict = file.contents()?;

  println!("Entries: {}", dict.entries.len());

  Ok(())
}

Python

import asyncio
from theopendictionary import OpenDictionary

async def main():
  # Load from disk
  dictionary = await OpenDictionary.load("./my-dictionary.odict")

  # Load from remote registry
  dictionary = await OpenDictionary.load("wiktionary/eng")

  print(dictionary.lexicon())

asyncio.run(main())

JavaScript

import { OpenDictionary } from "@odict/node";

// Load from disk
const dictionary = await OpenDictionary.load("./my-dictionary.odict");

// Load from remote registry
const dictionary = await OpenDictionary.load("wiktionary/eng");

console.log(dictionary.lexicon());