BookWeaver translates an EPUB into an alternating bilingual EPUB: each source paragraph is followed by its translation. It runs on your own subscription CLIs: Antigravity (agy, the default), Codex, or Claude Code. A paid API (Gemini, Anthropic) runs only with your consent for each run. EPUB is the only input format (ADR-0003).
Install Python 3.13+, uv, and an authenticated Antigravity CLI. Then:
uv sync --frozenuv run bookweaver book.epub --output translated.epub- The run translates in batches and saves progress after each batch.
- Add
--extract-glossaryto extract the book's key terms first, so the whole book translates them the same way (see Terms). The browser upload does this by default. - Run the same command again to resume after a failure or Ctrl-C. Finished batches are not translated again.
- To choose another model, list the presets and pass one:
uv run bookweaver presetsuv run bookweaver book.epub --output translated.epub --preset agy-pro-lowA paid preset (gemini-*, anthropic-*) costs money. It runs only with --allow-paid-api or when you type USE_API at the prompt, and that consent covers one run. A configuration file cannot give it.
uv run bookweaver serveOpen http://127.0.0.1:8765/docs, use POST /runs/upload to upload the EPUB and choose a preset, and read the progress with GET /runs/current. Uploaded books and their translations are kept in ~/Documents/BookWeaver/<book name>/.
Keep books, translations and checkpoints outside this program folder. A checkpoint is saved in .bookweaver_checkpoints/ beside the output file.
| Guide | Read it to |
|---|---|
| Presets and models | choose a model, set up Codex or Claude Code, compare models, run a paid API |
| Local API | use the browser page and the other endpoints |
| Terms | understand term extraction, supply your own glossary, run a Term Panel |
| Checkpoints, batches and configuration | resume rules, batch size, timeouts, configuration files, older checkpoints |
Contributor rules, verification commands and the current product boundary are in AGENTS.md. Validation status and remaining acceptance work are in SPEC-021. Architectural decisions are recorded in ADRs. Domain terms are defined in GLOSSARY.md.