bilingual_book_maker: building bilingual EPUBs with an LLM translation pass

What bilingual_book_maker does with a book file

The project describes itself as an AI translation tool that uses ChatGPT to assist users in creating multi-language versions of epub, txt, md, srt and pdf files and books. The output is a bilingual edition: the original text and the translation sit together in the same EPUB, which is the format the tool is built around.

The intended user is someone who already holds a book file and a model credential. There is no reader, no library, no account. You run a Python script against a file on disk. The README opens with a rights warning and points at a disclaimer file, and it asks users to work only with material they have the right to translate: works they hold rights to, suitably licensed or permitted works, public-domain books, or uses otherwise allowed by law. That framing tells you what the tool is for and what it is not: it is a production step, not a service.

The repository ships a sample book, test_books/animal_farm.epub, and a --test flag that translates only its first few paragraphs. That pairing is the whole onboarding story of the project. You can see the shape of the output before you spend anything meaningful on a full run.

How the translation pipeline is put together

The pipeline is a Python package, book_maker, driven by make_book.py at the repository root, with an installed entry point named bbook_maker declared in pyproject.toml. The dependency list is the architecture in miniature: ebooklib for EPUB reading and writing, bs4 for tag manipulation, PyMuPDF for PDF input, tiktoken for token accounting, tenacity for retries, rich for terminal output, and openai>=1.92.0 plus anthropic and google-genai for the model routes.

Endpoints are selected with --api_format, which names the API the endpoint speaks: openai, anthropic, gemini, qwen, groq, xai, litellm, codex, or one of the machine-translation engines (google, caiyun, deepl, deeplfree, tencent, customapi). A format that belongs to one vendor already knows that vendor's address, so the format plus a --key is a complete command. Any other OpenAI-compatible API is reached with --api_base ending in /v1, a --key, and the model id in --model. A third route, --provider, reads credentials from a JSON file, bbm_providers.json, copied from bbm_providers.example.json; the example carries an entry for Gemini, Qwen, xAI, Groq, OrcaRouter, Ollama, LiteLLM, SiliconFlow and OpenRouter.

The interesting design decision is tag classification. The README states that epub tag classification is auto enabled on JSON-schema endpoints and on any endpoint that can hold a conversation, where the model is asked for exact skip or translate verdicts. Only routes with no conversation at all, meaning the machine-translation engines, fall back to translating p tags only. The README is explicit that some poetry or verse may be omitted there. That is a real quality boundary between the two families of routes, and it is a consequence of what the endpoint can do, not a setting you can turn on.

Session mode is the other mechanism worth understanding. --use_context session translates in session mode, with history that compacts at 8k by default, overridable with --context-compact-at. It keeps one cached history for consistency and learns a glossary from its own handoff reports when --glossary-auto is set, so recurring names stay stable across a book. The README calls this the recommended mode on OpenAI-compatible endpoints.

Installing bbook-maker and running a first test translation

The README gives two install paths. The requirements file is a hash-pinned lock export, so installing from it puts pip in hash-checking mode. The published package is named bbook-maker on PyPI.

pip install -r requirements.txt      # or: pip install -U bbook_maker

Python 3.10 or newer is required, per both the README and the requires-python field in pyproject.toml. The Dockerfile shows the same install with no apt packages and no compiler, because the dependencies ship manylinux wheels.

The provider file is the cleanest way to hold credentials. Copy the example and edit base_url, default_models and env_key in the copy.

cp bbm_providers.example.json bbm_providers.json
python3 make_book.py --book_name test_books/animal_farm.epub --provider openai --test --use_context session

The --test flag translates only the first few paragraphs of the sample book, so the run finishes quickly and shows you the bilingual layout before you commit to the whole file. Session mode is what the README's examples use.

If you would rather pass the key on the command line, the README gives this form, with --api_base pointing at an OpenAI-compatible address:

python3 make_book.py --book_name test_books/animal_farm.epub \
  --key sk-... --model gpt-5.6-luna --api_base https://api.openai.com/v1 --test --use_context session

There is also a Codex route that spends a Codex subscription quota rather than an API key, selected with --api_format codex. The README adds a fourth path for people who would rather delegate the job: clone the repository, cd into it, and hand a coding agent a plain-language instruction naming the bbm-plan skill and the sample book. That is a documented convenience, not a required step.

Where the machine-translation routes fall short

The clearest limitation is stated by the project itself. On the machine-translation engines (google, caiyun, deepl, deeplfree, tencent, customapi) there is no conversation, so tag classification cannot be requested and the tool falls back to translating p tags only. Poetry and verse may be omitted. If the book you care about is not mostly paragraphs, the free and cheap routes are the wrong ones, and the fix is not a flag; it is a different endpoint class.

Cost and rate limits are the second constraint. The Gemini section notes that --interval sets the pause between requests, which is how the free tier's rate limit is stayed under. That is an admission that a long book on a free tier is a paced, slow job. The token accounting dependency, tiktoken, and the 8k default compaction point in session mode both exist because context is finite; the README does not claim the glossary survives compaction perfectly, and it does not document rollback if a run is interrupted. The Dockerfile comment is more informative than the README here: the CLI writes log/buglog.txt on every epub run and batch_files/ on the openai batch route, so there is a log to inspect, but no documented resume command.

Finally, the tool assumes you can supply the book. There is no store, no search, no lending. If your problem is finding a bilingual edition of a title, this project does not address it at all.

bilingual_book_maker against a plain translation API script

The obvious alternative is a short script of your own: read the EPUB with ebooklib, walk the paragraphs, send each one to a translation API, and write the results back. That is essentially the core of this tool, and for a single plain novel it is not a large amount of code.

The difference is in what surrounds the core. Here you get tag classification that asks the model for skip or translate verdicts on conversation-capable endpoints, session history that compacts at a configurable threshold, an automatic glossary that keeps recurring names stable, one interface across nine API formats plus six machine-translation engines, a provider file so credentials do not live in your shell history, token counting, retries, and a Docker image that pre-creates the writable log and batch directories. A hand-rolled script gets none of that unless you write it.

The trade-off runs the other way too. A script you wrote has no undocumented behaviour and no dependency on the project's endpoint abstractions; the README notes that older flags such as --model gpt4o, --model gemini and --openai_key still work, with a migration document, which tells you the interface has moved and carries compatibility weight. If your input is a single well-formed EPUB and your endpoint is one vendor, the script is a smaller thing to own. If your inputs vary in format and your endpoints vary by cost, the abstraction earns its place.

Licence, maintenance and the cost of upgrading

The project is MIT licensed, stated in both the README badge and the license field of pyproject.toml. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are kept. That covers the tool. It does not cover the books you put through it, and the README's own framing is that you must have the right to translate the material you feed in. Those are two separate questions, and the licence answers only the first. Nothing here is legal advice; read the disclaimer file in the repository and the licence text itself.

On maintenance, the repository is not archived and the last push was on 2026-09-20, one day before this was written. Releases v1.2.0 and v1.2.1 landed on 2026-09-10 and 2026-09-14, after a long gap back to v0.9.8 in November 2024. The version is derived from SCM tags, so there is no hand-maintained version string to drift.

Upgrade cost is concentrated in the endpoint layer. The openai floor is 1.92.0 because chat.completions.parse, the Structured Outputs call, is unavailable before it, and that call is what the JSON-schema tag classification path depends on. requirements.txt is generated by PDM from pdm.lock and is hash-pinned, so a dependency bump means regenerating the lock rather than editing the requirements file. The Dockerfile installs from that lock and copies book_maker/ and make_book.py, so a container rebuild picks up code changes without reinstalling dependencies.

Editorial conclusion

Adopt it if you have a book file you are permitted to translate, an API key, and a terminal; the session context mode and the --test flag make a first run cheap. Do not adopt it if you want an Android app, a hosted website, or a free service, because the project ships none of those and the machine-translation engines are the only routes that need no key. Before a full run, confirm the tag classification route your endpoint takes, since the MT engines translate p tags only and can drop verse, and check the disclaimer file for the rights position.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. yihong0618/bilingual_book_maker on GitHub