Self-hosted AI-powered web novel reader & translator with complete privacy.
ReadOmni AI lets you read, crawl, and translate Chinese web novels using local or cloud AI — with zero data leaving your network. Import EPUBs, scrape from URLs, batch-translate chapters, manage glossaries, and export polished EPUBs — all from a single self-hosted dashboard.
- Features
- Tech Stack
- Quick Start
- Configuration
- Architecture
- Documentation
- Troubleshooting
- Contributing
- License
- Multi-provider support — LM Studio (local), Google Gemini, OpenAI with seamless switching
- Quality / Fast mode — Quality mode for cloud (full glossary, style guide), Fast mode for local LLMs (10K token cap)
- Auto-continue — Detects truncated translations and automatically continues until complete
- Batch translation — Translate hundreds of chapters with real-time progress tracking
- Smart glossary — AI-extracted terms with usage tracking, auto-injection into prompts
- Style guide per novel — Define translation tone and rules, injected into Quality mode
- Multiple API keys — Store and rotate keys per provider to distribute free-tier quotas
- Glassmorphic UI — 6 theme presets (Obsidian, OLED, Sepia, White, Omni, Black)
- Mobile-first — Bottom navigation, gesture-friendly layout, floating toolbars
- Bookmark sync — Exact scroll position saved per chapter, restored on revisit
- Markdown rendering — Bold/italic formatting preserved in reader and EPUB export
- EPUB import/export — Upload EPUBs, compile translations back with custom covers
- URL scraping — Crawl chapters from web URLs with ad/noise stripping
- SFACG integration — Direct metadata and chapter scraping from SFACG
- Cover editor — Canvas-based cover compression (<100KB) with gradient fallbacks
- Delete chapters — Remove individual chapters with automatic re-ordering
- Fix truncated — Detect and reset translations cut off mid-sentence
- TOC detection — Auto-skips Table of Contents pages to prevent AI hallucination
- Character relationship graph — Interactive D3 force-directed graph of extracted relationships
- Hallucination detection — Automated detection of garbled output and repeated patterns
- TXT/EPUB cleaners — Strip ads, noise, and false chapters from imported content
- Glossary up to 1000 terms — Usage-ranked term injection with LFU eviction
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite 8, TailwindCSS v4, Radix UI |
| Backend | Python 3.11, FastAPI, SQLAlchemy 2.0 |
| Database | SQLite (WAL mode) |
| AI Providers | LM Studio, Google Gemini, OpenAI |
| Scraping | Crawl4AI, BeautifulSoup4 |
| EPUB | EbookLib |
| Testing | pytest (backend) |
- Node.js v20+
- Python 3.11+
- AI Provider (one of):
- LM Studio running on port 1234 (free, local)
- Google AI Studio API key (free tier available)
- OpenAI API key (paid)
cd backend
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
pip install -r requirements.txt
py -m uvicorn main:app --reload --port 8000 --host 0.0.0.0npm install
npm run devOpen http://localhost:5173 or use your local IP (e.g., http://192.168.1.50:5173) for mobile access.
Create backend/.env (gitignored):
OPENAI_API_KEY=sk-your-key-here
GEMINI_API_KEY=AIzaSy-your-key-hereAll configuration is available in the app's Settings page:
| Setting | Description |
|---|---|
| AI Provider | LM Studio / OpenAI / Gemini |
| Model | Provider-specific model selection (Gemini: gemini-2.5-flash, gemini-3-flash, gemma-4-31b, etc.) |
| Target Language | Indonesian / English |
| Translation Mode | Quality (cloud, full glossary) / Fast (local, 10K cap) |
| Token Safety Cap | 7K / 15K / 22K / 30K / Off |
| Glossary Limit | 20-1000 terms per thread |
| API Keys | Multiple keys per provider with auto-rotation |
| Prefetch | 1-5 chapters ahead, soft/hard mode |
| Theme | 6 glassmorphic presets |
Translator_Web/
├── backend/
│ ├── main.py # FastAPI app entry
│ ├── database.py # SQLAlchemy models & auto-migration
│ ├── routers/ # API endpoints (13 routers)
│ ├── services/
│ │ ├── ai/ # Provider adapters (Gemini, OpenAI, LM Studio)
│ │ ├── background_translator.py # Batch engine with auto-continue
│ │ ├── context_engine.py # Prompt builder & glossary injection
│ │ └── cleaner_tools.py # TXT/EPUB cleanup pipelines
│ └── tests/ # pytest test suite configuration
├── src/
│ ├── pages/ # 6 main pages
│ ├── components/ # Reusable UI components
│ └── hooks/ # Custom React hooks
└── docs/
├── decisions/ # 51 Architectural Decision Records
├── Handoff.md # Developer onboarding guide
└── SDLC.md # Development lifecycle docs
| Document | Description |
|---|---|
| Handoff Guide | Developer onboarding, architecture overview |
| SDLC | Software development lifecycle |
| ADRs | 51 architectural decision records |
| Implementation Plan | Task definitions & acceptance criteria |
| Issue | Solution |
|---|---|
| Themes look dark/wrong | Disable Dark Reader or Opera GX "Force Dark Pages" extension |
| Vite keeps reloading | Check vite.config.ts ignores backend/ and .db files |
| Gemini 400 error | Model doesn't support thinking mode — app auto-disables for incompatible models |
| TOC pages hallucinated | Auto-detected and skipped (5+ chapter indicators in <5000 chars) |
| Translations truncated | Use "Fix Truncated" button in Library menu, then re-translate with overwrite |
See CONTRIBUTING.md for guidelines.
# Run tests
cd backend && py -m pytest tests/ -v
npm run lint && npm run buildMIT License. See LICENSE for details.
This application is 100% self-hosted. No data leaves your network unless you explicitly configure a cloud AI provider. No analytics, no tracking, no external APIs.
Built with care for the web novel translation community.