Offline-first decodable literacy toolkit for African languages.
Soma (Kiswahili for "read") is an open-source toolkit that turns structured phonics lessons into a single HTML file that teaches children to read, fully offline, on the devices families actually have: low-end Android phones, school tablets, SD cards, and USB sticks.
- In sub-Saharan Africa, roughly 9 in 10 children cannot read and understand a simple text by age 10 (World Bank learning poverty estimate, 2024-2025).
- African languages written in Latin script have largely transparent orthographies (regular letter-sound mappings), which makes systematic phonics the evidence-based route to early reading - yet nearly all open-source phonics tooling is English-only and assumes an internet connection.
- Content authoring and distribution for local languages is manual, offline-hostile, and non-portable. Soma provides a small standard for that.
See RESEARCH.md for the evidence base with sources and docs/DESIGN.md for the benchmarked reader design decisions.
| Package | What it does |
|---|---|
packages/soma-core |
Zero-dependency JavaScript library: orthography profiles (sw, en, zul, nya), syllabification, decodable word generation, decodability checking, pack validation, difficulty analysis |
packages/soma-cli |
Zero-dependency Node.js CLI: init, validate, build, stats, serve |
packages/soma-reader |
The offline reader: a single-file web app that runs from file://, an SD card, or any static host, with a service worker for offline use |
packs/sw-grade1 |
Starter pack: Kiswahili Grade 1 phonics, 12 lessons (real, curated content) |
packs/en-grade1 |
Starter pack: English Grade 1 synthetic phonics, 12 lessons (satpin sequence) |
packs/zul-draft1 |
Draft isiZulu starter, 5 lessons (awaiting native-speaker review) |
packs/nya-draft1 |
Draft Chinyanja (Chichewa) starter, 5 lessons (awaiting native-speaker review) |
site/ |
Landing page deployed to GitHub Pages |
Live demos: https://mdanielseo.github.io/soma/ (landing page, links to the Kiswahili and English readers)
Requirements: Node.js 20+ (the CLI uses no third-party packages).
# validate a pack
node packages/soma-cli/bin/soma.js validate packs/sw-grade1
# build a single offline HTML file (reader + lessons inlined)
node packages/soma-cli/bin/soma.js build packs/sw-grade1 -o demo
# -> demo/index.html (~30 KB, works offline, shareable via SD card / Bluetooth / WhatsApp)
# size report with estimated mobile-data cost in selected markets
node packages/soma-cli/bin/soma.js stats packs/sw-grade1
# scaffold a new pack
node packages/soma-cli/bin/soma.js init packs/my-language --lang swOpen the built index.html in any browser. No server, no accounts, no network
requests. The reader uses the device text-to-speech engine when a Kiswahili voice
is installed and falls back to visual syllable highlighting when it is not.
A soma pack is a folder with a pack.json and JSON lesson files. Lessons introduce
graphemes cumulatively; every word and sentence is checked against the taught
grapheme set so that nothing appears in a lesson that the child has not been
taught to decode (with an explicit sight-word list for high-frequency words like
na / ni). See docs/SPEC.md.
Version 0.1. New project. The core, CLI, reader, and Kiswahili pack are functional and tested; the pack content has been authored for linguistic correctness but has not yet been reviewed by a native-speaker literacy specialist (that review is the top roadmap item). See docs/ROADMAP.md.
Contributions are welcome: more language profiles, more packs, audio assets, TTS voice mappings, and reader improvements. See CONTRIBUTING.md. Please read the content-accuracy rules there before adding language content.
MIT. See LICENSE.
Maintainer: Daniel Seo, mdanielseo@gmail.com