Bilingual Book Maker

中文 | English

The bilingual_book_maker is an AI translation tool that uses ChatGPT to assist users in creating multi-language versions of epub/txt/md/srt/pdf files and books. Use it only with material you have the right to translate — works for which you hold the necessary rights, suitably licensed or permitted works, public-domain books, or uses otherwise allowed by applicable law. Before using this tool, please review the project's disclaimer.

Guides for every file type and option, and the measurements behind the defaults, are on the wiki. If you use a coding agent (Codex, Claude Code), the repository's skill translates a book for you: Translate with an agent.

Supported endpoints

OpenAI and Anthropic format endpoints are supported. Usually it comes with three fields, two if you are using the official endpoints, such as gpt-6-luna (the default) or claude-sonnet-4-6. Specify openai, or anthropic at --api_format for API request formats. This argument also supports selecting some translation services (google, caiyun, deepl, deeplfree, tencent, customapi — not an OpenAI format) or codex if you want to use your Codex quota instead.

--provider is an alternative way to pass credentials, through a JSON config file bbm_providers.json.

Epub tags classification is auto enabled on JSON-schema endpoints, and on any endpoint that can hold a conversation — the codex route and plain reseller proxies included — where the model is asked for exact skip/translate verdicts instead. Only routes with no conversation at all (the MT engines) fall back to translating p tags only, so some poetry or verse may be omitted there. See Plan mode for details.

Older flags (--model gpt4o, --model gemini, --openai_key, …) still work: see Models and languages.

Preparation

1. ChatGPT or OpenAI token ¹
2. epub/txt/md/pdf books
3. Environment with internet access or proxy
4. Python 3.10+

Quick Start

A sample book, test_books/animal_farm.epub, is provided for testing purposes. --test translates only its first few paragraphs.

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

Then:

cp bbm_providers.example.json bbm_providers.json
# edit base_url, default_models and env_key in ./bbm_providers.json
python3 make_book.py --book_name test_books/animal_farm.epub --provider openai --test --use_context session

You can also pass the key on the command line:

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

To spend a Codex subscription:

python3 make_book.py --book_name test_books/animal_farm.epub --model gpt-6-luna --api_format codex --test

Or hand it to a coding agent

git clone https://github.com/yihong0618/bilingual_book_maker.git
cd bilingual_book_maker
codex "Hi, please use bbm-plan to translate this book: test_books/animal_farm.epub into a bilingual Chinese-English edition, thanks."

Endpoint flags

• --api_format names the API the endpoint speaks: openai, anthropic, gemini, qwen, groq, xai, litellm, codex, or one of the translation services (google, caiyun, deepl, deeplfree, tencent, customapi). A format that belongs to one vendor already knows that vendor's address, so the format and a --key are a whole command.
• Any other OpenAI-compatible API: --api_base (ending in /v1), --key the API key, and the model id in --model. Omit --api_base for OpenAI's own API, and --model for gpt-6-luna.
• Or translate through --provider: bbm_providers.example.json has an entry for each vendor below (Gemini, Qwen, xAI, Groq, OrcaRouter, Ollama, LiteLLM, SiliconFlow, OpenRouter). Copy it to bbm_providers.json, set the key in it, and --provider gemini uses the Gemini API from it.
• --use_context session translates in session mode; the history compacts at 8k by default (--context-compact-at overrides). It keeps one cached history for consistency, so recurring names stay stable across the book, and can also learn a glossary from its own handoff reports (--glossary-auto on, off by default) — the recommended mode on OpenAI-compatible endpoints, and what the examples below use.
• The old preset names and key flags still work, see Migrating from the old flags.

Footnotes

1. You can get a token from OpenAI or Anthropic. ↩

This is the beginning of the README. Read the rest at the original. Read the full README ↗