English | 中文

OpenVoca

Build vocabulary naturally through reading.

A minimalistic, LLM-powered English vocabulary tool —
learn new words by reading AI-generated sentences in context.

What is OpenVoca?

OpenVoca helps you build English vocabulary through reading. Instead of memorizing flashcards in isolation, you read short passages generated by an LLM that naturally incorporate words you need to practice.

How it works:

1. Read — An AI generates a sentence containing your target vocabulary words.
2. Mark — Tap any unfamiliar word in the sentence to add it to your word bank.
3. Repeat — The system tracks each word's familiarity and resurfaces it at the right time.

Over many rounds, your vocabulary grows organically through meaningful context rather than rote memorization. The spaced-repetition algorithm ensures words you struggle with appear more frequently, while mastered words fade into the background.

OpenVoca is fully local and private. Your data stays on your machine, and you bring your own LLM endpoint (Ollama, OpenRouter, Groq, SiliconFlow, or any OpenAI-compatible API).

---

Architecture

OpenVoca is a monorepo containing both frontend and backend.

• Frontend: Vue 3 + TypeScript + Vite + Tailwind CSS v4 See frontend/README.md for startup & testing details.
• Backend: Python 3.12+ (managed by uv) + FastAPI + SQLModel + SQLite See backend/README.md for API & testing details.

Testing

This project follows Test-Driven Development (TDD):

• Frontend: pnpm run check in the frontend/ directory
• Backend: uv run ruff format --check .; uv run ruff check .; uv run pytest in the backend/ directory
• Both: VS Code task ✅ Check OpenVoca (All)

Building a Release Package

uv run python scripts/bundle.py

Produces dist/openvoca-{version}-win-x64.zip — a self-contained Windows package requiring no installation. See scripts/bundle.py for details.

Versioning and Contribution

• Version: VERSION at the repository root (single source of truth)
• Contributing: See CONTRIBUTING.md
• Releases: See RELEASE.md

License

Copyright (C) 2026 OpenVoca Contributors

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You are free to use, modify, and distribute this software under the terms of the AGPL-3.0. Any modified version distributed or run as a network service must also be released under the AGPL-3.0 with source code made available.

Commercial use is permitted under AGPL-3.0 terms.

The built-in dictionary data is derived from ECDICT, licensed under the MIT License.