A developer-centric reference project and high-performance compilation pipeline showing how to build custom, search-compliant Kindle bilingual and monolingual dictionaries from raw lexicographical datasets.
Official documentation on building custom Kindle dictionaries is notoriously sparse, fragmented, and outdated. This repository serves as a modern, open-source boilerplate to demystify Kindle's proprietary formatting standards.
By analyzing this codebase, you can easily adapt the pipeline to compile high-fidelity dictionaries for any language pair. The project highlights four essential implementation areas:
- XHTML Schema Compliance (
idxNamespace): Demonstrates how to structure dictionary entries using standard Kindle markup elements—such as<idx:entry>,<idx:orth>, and<idx:infl>—to allow Kindle's indexing system to parse and index inflections successfully. - OPF Package Metadata Configuration: Shows how to properly structure target and source languages (
DictionaryInLanguage,DictionaryOutLanguage) and declare lookup indexes inside the mandatory<x-metadata>block of the.opfmanifest. - Database Integration & Normalization: Standardizes, deduplicates, and merges unstructured source data (from SQLite or JSON formats) into a unified relational database before sharding the output into size-compliant XHTML files to prevent compiler crashes.
- Embedded KindleGen Toolchain Invocation: Automatically resolves and calls Amazon's Kindle compiler from a Python environment, ensuring compatibility on both local setups and headless CI/CD runner pipelines.
This diagram illustrates how raw source lexicons are ingested, consolidated, formatted into Kindle-compliant markups, and compiled into optimized dictionary files:
┌────────────────────────────────────────────────────────────────────────┐
│ DATA PIPELINE ARCHITECTURE │
└────────────────────────────────────────────────────────────────────────┘
[ Raw Lexicons ] [ Normalization & DB ] [ Document Generation ]
┌──────────────┐ ┌────────────────────┐ ┌─────────────────────┐
│ MinhasKamal │───┐ │ │ │ XHTML Sharding │
└──────────────┘ │ │ │ │ (Max 1000 entries) │
┌──────────────┐ │ │ │ │ ┌────────────────┐ │
│ Aparajeyo │───┼───>│ kindle_dictionary_ │────────>│ │ content_N.html │ │
└──────────────┘ │ │ builder.py │ │ └────────────────┘ │
┌──────────────┐ │ │ │ │ - xmlns:idx markup │
│ Ridmik │───┤ │ │ │ - <idx:entry> tags │
└──────────────┘ │ │ - SQLite Staging │ └──────────┬──────────┘
┌──────────────┐ │ │ (lexicon.db) │ │
│ Ankur │───┤ │ - Deduplication │ ▼
└──────────────┘ │ │ - Normalization │ ┌─────────────────────┐
┌──────────────┐ │ └────────────────────┘ │ OPF Meta / Nav XML │
│ Wiktionary │───┤ │ - dict.opf │
└──────────────┘ │ │ - nav.html │
┌──────────────┐ │ └──────────┬──────────┘
│ Hunspell │───┤ │
└──────────────┘ │ ▼
┌──────────────┐ │ ┌─────────────────────┐
│ BoiBhai │───┤ │ Tri-Directional │
└──────────────┘ │ │ Kindle MOBI Books │
┌──────────────┐ │ └──────────┬──────────┘
│MuntashirAkon │───┘ │
└──────────────┘ │
▼
[ Compiler Invocation ] [ Distribution ]
┌────────────────────────────────────────────────┐ ┌─────────────────────┐
│ Kindle Previewer 3 Toolchain │ │ Direct Sideload │
│ ┌──────────────────────────────────────────┐ │ │ (USB to device) │
│ │ Embedded kindlegen Compiler │ │ └──────────▲──────────┘
│ └────────────────────┬─────────────────────┘ │ │
│ │ ├────────────────┘
│ ▼ │
│ ┌──────────────────────────────────────────┐ │ ┌─────────────────────┐
│ │ High-Fidelity .MOBI Outputs │──┼────>│ GitHub Releases │
│ │ - Shobdo_Vandar_en-bn_v1.5.2.mobi │ │ │ (Automated CI) │
│ │ - Shobdo_Vandar_bn-en_v1.5.2.mobi │ │ └─────────────────────┘
│ │ - Shobdo_Vandar_bn-bn_v1.5.2.mobi │ │
│ └──────────────────────────────────────────┘ │
└────────────────────────────────────────────────┘
This repository began as a personal hobby project. The goal was twofold: to gain a practical understanding of writing robust Python scripts and managing GitHub CI/CD workflows, and to create an accurate, highly responsive dictionary for reading Bangla literature on a Kindle.
The codebase was developed in close collaboration with an AI pair-programmer:
- Assistant: Antigravity (an agentic AI developer)
- Cognitive Model: Gemini 3.5 Flash (responsible for parsing optimizations, SQL querying structures, and automated tests)
This project demonstrates how pairing standard developer workflows with AI capabilities can produce reliable, production-ready output from fragmented, legacy documentations.
You do not need to build these files manually. The compilation pipeline runs automatically on every release, compiling and attaching ready-to-use .mobi files to the release page.
- Navigate to the Releases page.
- Download the dictionary binary you need from the assets section:
Shobdo_Vandar_en-bn_v1.5.2.mobi(English-to-Bangla: 94,348 entries, ~10.4 MB)Shobdo_Vandar_bn-en_v1.5.2.mobi(Bangla-to-English: 50,928 entries, ~6.4 MB)Shobdo_Vandar_bn-bn_v1.5.2.mobi(Bangla-to-Bangla: 46,552 entries, ~9.2 MB)
To load the compiled dictionaries onto any physical Kindle (including Kindle Paperwhite, Oasis, Scribe, and Basic models):
- Connect your Kindle to your computer via a USB cable.
- Open your system file manager and navigate to the mounted Kindle directory.
- Copy the downloaded
.mobifiles into the Kindle'sdocuments/dictionaries/folder:Kindle/ └── documents/ └── dictionaries/ ├── Shobdo_Vandar_en-bn_v1.5.2.mobi ├── Shobdo_Vandar_bn-en_v1.5.2.mobi └── Shobdo_Vandar_bn-bn_v1.5.2.mobi - Safely eject the Kindle from your computer.
- Activate the Dictionaries:
- On your device, go to Settings ➔ Language & Dictionaries ➔ Dictionaries.
- Under the English language category, select Shobdo Vandar English-to-Bangla Dictionary.
- Under the Bangla language category, select Shobdo Vandar Bangla-to-English Dictionary and Shobdo Vandar Bangla-to-Bangla Dictionary.
- Highlight any English or Bangla word inside an e-book to view instant, context-rich definitions.
This project was natively designed and developed on macOS (Apple Silicon/Intel), leveraging Amazon's official macOS Kindle Previewer 3 installation to compile high-fidelity .mobi dictionaries.
However, because the dictionary-building script is written in standard cross-platform Python, Windows and Linux users can easily run the compilation suite locally by following standard setup instructions.
Regardless of your operating system, you will need:
- Python 3.8+ (with standard libraries).
- KindleGen compiler (Amazon's proprietary MOBI dictionary compiler).
Below are the step-by-step instructions for setting up the toolchain on your preferred environment:
- Setup Step: Install the official Kindle Previewer 3.
- Compiler Resolution: The python builder script automatically resolves standard macOS installation folders (e.g.
/Applications/Kindle Previewer 3.app) to locate the embeddedkindlegenexecutable.
- Setup Step: Install the official Kindle Previewer 3 for Windows.
- Compiler Resolution:
- Once installed, copy the compiler
kindlegen.exefrom your local application data path:C:\Users\<Your_Username>\AppData\Local\Amazon\Kindle Previewer 3\lib\fc\bin\kindlegen.exe - Paste it directly into the root folder of this repository as
kindlegen.exe. The script will automatically detect and use it. - Once Python 3 and the
kindlegen.exebinary are in the root directory, the workflow is identical to macOS.
- Once installed, copy the compiler
- Setup Step: Amazon does not distribute Kindle Previewer 3 for Linux, but you can utilize the final official standalone KindleGen v2.9 for Linux release.
- Download the legacy 32-bit Linux tarball from the Internet Archive Mirror or other reliable sources.
- Extract the
kindlegenbinary and copy it to the root of this repository. - Make it executable:
chmod +x kindlegen - CRITICAL STEP: Because the legacy KindleGen is a 32-bit executable, modern 64-bit Linux distributions (like Ubuntu/Debian 64-bit) require 32-bit execution compatibility libraries. Install them by running:
sudo apt-get update sudo apt-get install libc6-i386
- Execution succeeds perfectly once the 32-bit compatibility package is installed on the host.
-
Clone the Repository:
git clone https://github.com/tahmidxp96/Shobdo-Vandar.git cd Shobdo-Vandar -
Run the Complete Build Suite (performs database staging, consolidation, and full MOBI generation for all 3 directions):
python3 kindle_dictionary_builder.py
-
Recompile MOBI Binaries Only (skips raw ingestion stages for rapid pipeline prototyping):
python3 kindle_dictionary_builder.py -c
-
Preview Dictionary Layouts Directly in Terminal: You can verify how an entry is displayed on Kindle popups and full-page layouts using the terminal lookup previewer:
python3 kindle_dictionary_builder.py -p "benevolent" # Or monolingual lookup python3 kindle_dictionary_builder.py -p "হিতৈষী"
The builder compiles custom dictionaries by normalising data across multiple staging references:
| Source | Records Processed | Translation Pathway | Primary Lexical Characteristics | Link | License |
|---|---|---|---|---|---|
| Aparajeyo | 186,776 | English ➔ Bangla | Comprehensive synonym groups and parts of speech | Aparajeyo Community | Open Source |
| MinhasKamal | 93,421 | English ➔ Bangla | Standard colloquial vocabulary mapping | MinhasKamal/BengaliDictionary | MIT License |
| Ridmik | 13,474 | Bangla ➔ English | Standardized lexical mappings | Ridmik Keyboard | MIT License |
| Ankur | 1,984 | English ➔ Bangla | Traditional terminology vocabulary | Ankur Project | GPL License |
| Wiktionary | 24 | English ➔ Bangla | Collaborative contextual examples & POS tags | Wiktionary | CC-BY-SA 3.0 |
| Hunspell | 30 | Bangla ➔ English | Orthographical verified spelling lemmas | Hunspell BN | LGPL / GPL |
| BoiBhai | 11 | Bangla ➔ Bangla | Crowdsourced native monolingual glossary | BoiBhai bn-dict | Open Source |
| MuntashirAkon | 46,551 | Bangla ➔ Bangla | Comprehensive HTML definitions, POS, and Sanskrit etymology | MuntashirAkon/BanglaDictionary | GPL License |
- English-to-Bangla (
en-bn):94,348unique entries - Bangla-to-English (
bn-en):50,928unique entries - Bangla-to-Bangla (
bn-bn):46,552unique entries - Total Combined Database:
191,828deduplicated, high-fidelity words
This repository utilizes GitHub Actions (.github/workflows/release.yml) for continuous deployment.
Whenever a release version tag (e.g., v1.5.2) is pushed to the repository:
- A fresh macOS environment is provisioned on GitHub runners.
- The latest Kindle Previewer 3 package is dynamically fetched and installed.
- The
kindle_dictionary_builder.pyscript initializes the ingestion pipeline, performs standardizations, and runs the MOBI compilation for all three targets. - The workflow bundles the completed
.mobibinaries and publishes them directly to your repository's Releases page.
The builder and compilation pipeline scripts are distributed under the MIT License. All raw lexicographical resources remain the intellectual property of their respective authors and projects:
- MinhasKamal (Bangla Dictionary): Large-scale English-to-Bangla translation mappings hosted at the MinhasKamal/BengaliDictionary repository (licensed under the permissive MIT License).
- Aparajeyo Dictionary: Compiled English-to-Bangla and Bangla-to-English database compiled by Nazmul Hossain Nihal and the open-source Aparajeyo Bangla Express Community.
- Ridmik Dictionary: Open-source Bangla-to-English dictionary assets by Ridmik Labs, creators of the open-source Ridmik Keyboard.
- Ankur Dictionary: English-to-Bangla translation terminology database compiled by the open-source Ankur Bangla Project (distributed under the GPL License).
- Wiktionary Bilingual Dataset: Collaborative community-driven definitions and bilingual translations from Wiktionary (distributed under the CC-BY-SA 3.0 License).
- Hunspell Spelling Dictionary: Standardized Bengali spell-checker lemmas and orthographical reference definitions from Hunspell / hunspell-bn (distributed under the LGPL/GPL License).
- BoiBhai Monolingual Dictionary: Crowdsourced and collaborative Bengali-to-Bengali monolingual dictionary containing pronunciation, etymology, ontology, and native definition data from BoiBhai bn-dict-database.
- MuntashirAkon Monolingual Dictionary: Extensive Bangla-to-Bangla monolingual definitions and grammatical etymologies from MuntashirAkon/BanglaDictionary (distributed under the GNU GPL License).