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.

Supported translation services

• DeepL Support DeepL model DeepL Translator need pay to get the token

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format deepl --key ${deepl_key}
  

• DeepL free

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format deeplfree
  

• Claude

  A claude-* model id selects the anthropic format on its own.

  python3 make_book.py --book_name test_books/animal_farm.epub --model claude-sonnet-4-6 --key ${claude_key}
  

• Google Translate

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format google
  

• Caiyun Translate

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format caiyun --key ${caiyun_key}
  

• Gemini

  Google Gemini, over the Gemini API itself. Name any Gemini model id; without --model it is gemini-flash-latest. --interval sets the pause between requests, which is how the free tier's rate limit is stayed under.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format gemini --key ${gemini_key} --model gemini-flash-latest
  

• Qwen

  Qwen-MT on DashScope, a translation model: the request states a source and a target language. qwen-mt-turbo (the default) and qwen-mt-plus are supported, and --source_lang states the source language when auto-detection is not wanted.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format qwen --key ${qwen_key} --model qwen-mt-turbo --language "Simplified Chinese"
  

• Tencent TranSmart

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format tencent
  

Custom API Provider

When the built-in models do not cover your needs, define a provider in a JSON config file. Without a code change, any OpenAI-compatible or Anthropic-format API (SiliconFlow, a local proxy, ...) becomes usable.

Create bbm_providers.json in the current directory (or ~/.bbm/providers.json):

{
  "providers": {
    "siliconflow": {
      "api_style": "openai",
      "base_url": "https://api.siliconflow.cn/v1",
      "default_models": ["Qwen/Qwen2.5-72B-Instruct"],
      "env_key": "BBM_SILICONFLOW_API_KEY"
    },
    "openai": {
      "api_style": "openai",
      "base_url": "https://api.openai.com/v1",
      "default_models": ["gpt-6-luna"],
      "env_key": "OPENAI_API_KEY",
      "prices": {
        "gpt-6-luna": {"input": 0.10, "output": 0.50, "cached_input": 0.01}
      }
    }
  }
}

Config fields:

Field	Required	Description
api_style	Yes	API request format: openai, anthropic, gemini, qwen, groq, xai or litellm
base_url	No	The API address. Omitted means the api_style's default address
default_models	No	Default model list. Required if --model is not provided
env_key	No	Environment variable name for API key. Required if --key is not provided
prices	No	Prices per million tokens, per model: {"<model id>": {"input": …, "output": …, "cached_input": …}}. When every model in the run has a price, the progress bar shows money spent (spent=$0.012) instead of token counts, and the closing line shows both. Without cached_input, cache reads are charged at the input price. A model without a price puts the bar back on tokens, and the closing line names it
currency	No	Currency code for the prices, default USD. USD, EUR, GBP, CNY and JPY print with their symbol; any other code prints after the amount, as in 0.500 CHF

The spent amount and the token counts are estimates, accumulated from the usage each request reports — close enough to steer by, but the vendor's bill is the number that counts.

Priority: project-level ./bbm_providers.json overrides global ~/.bbm/providers.json.

--model names a model at that provider; without it the first of default_models is used.

python3 make_book.py --provider siliconflow --key sk-xxx --book_name test_books/animal_farm.epub --use_context session

export BBM_SILICONFLOW_API_KEY=sk-xxx
python3 make_book.py --provider siliconflow --book_name test_books/animal_farm.epub --use_context session

Usage

• Once the translation is complete, a bilingual book named ${book_name}_bilingual.epub would be generated for EPUB inputs; for TXT, MD and SRT inputs a bilingual file named ${book_name}_bilingual.txt, ${book_name}_bilingual.md or ${book_name}_bilingual.srt will be generated. For PDF inputs the tool will produce a bilingual .txt fallback and will also attempt to create ${book_name}_bilingual.epub — if EPUB creation fails, the TXT fallback remains so you do not need to retranslate.
• If there are any errors or you wish to interrupt the translation by pressing CTRL+C, a temporary bilingual file (for example {book_name}_bilingual_temp.epub or {book_name}_bilingual_temp.txt) would be generated. You can simply rename it to any desired name.

Params

• --model:

  The model id, exactly as the endpoint spells it. On the OpenAI format the default is gpt-6-luna. The second column is the --api_format the id needs:

  model	--api_format	notes
  gpt-6-luna	openai	the default, at OpenAI's own address
  claude-sonnet-4-6	anthropic	Anthropic's own address
  gpt-4o-mini	openai	OpenAI
  gemini-flash-latest	gemini	the default there, at Google's own address
  qwen-mt-turbo	qwen	the default there, on DashScope
  llama-3.3-70b-versatile	groq	Groq's own address

  The old preset values still parse and are rewritten to a real model id with a note; Migrating from the old flags lists them. Anything else is an endpoint: --api_base <url> --key <key> --model <id>, or a --provider entry (see the Custom API Provider section).

• --key:

  API key for the endpoint. Without the flag the key is read from $BBM_API_KEY, then from the format's own variable. Same flag as --api_key.

• --api_format:

  The API the endpoint speaks. When omitted it is inferred: an anthropic.com host, or a model id containing claude with no --api_base, means anthropic; anything else means openai. Pass it when the guess is wrong, to reach a vendor without typing its address, or to pick an engine.

  format	key	notes
  openai (default)	required: --key, else $BBM_API_KEY, $OPENAI_API_KEY; not for a local address such as Ollama

Examples

Note if use pip install bbook_maker all commands can change to bbook_maker args

# Test quickly
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --test --language zh-hans --use_context session

# Test quickly for src
python3 make_book.py --book_name test_books/Lex_Fridman_episode_322.srt --key ${openai_key} --test

# Or translate the whole book
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --language zh-hans --use_context session

# Gemini
python3 make_book.py --book_name test_books/animal_farm.epub --api_format gemini --key ${gemini_key} --model gemini-flash-latest

# Translate an EPUB with parallel chapter processing
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --parallel-workers 4

# Rotate across several models
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --model_list gpt-5-mini,gpt-4o-mini

# Set env OPENAI_API_KEY to leave out --key
export OPENAI_API_KEY=${your_api_key}

# Name a model and add context, translating to Japanese
python3 make_book.py --book_name test_books/animal_farm.epub --model gpt-4o --use_context --language ja

# Any OpenAI-compatible endpoint: base URL, key, and the model id it uses
python3 make_book.py --book_name test_books/animal_farm.epub --api_base "https://api.lingyiwanwu.com/v1" --key ${key} --model yi-34b-chat-0205 --use_context session

# DeepL, to Japanese
python3 make_book.py --book_name test_books/animal_farm.epub --api_format deepl --key ${deepl_key} --language ja

# Claude, to Japanese
python3 make_book.py --book_name test_books/animal_farm.epub --model claude-sonnet-4-6 --key ${claude_key} --language ja

# A custom translation API, to Japanese
python3 make_book.py --book_name test_books/animal_farm.epub --api_format customapi --api_base ${custom_api} --language ja

# A provider entry (e.g. SiliconFlow); the key comes from the entry's env_key
python3 make_book.py --book_name test_books/animal_farm.epub --provider siliconflow --language ja --use_context session

# Translate contents in <div> and <p>
python3 make_book.py --book_name test_books/animal_farm.epub --translate-tags div,p

# Plan mode: auto-discover translatable content (poetry, blockquotes, table cells,
# ...) and batch verse lines in stanza windows; preview the plan with --plan-dry-run
python3 make_book.py --book_name test_books/animal_farm.epub --plan-dry-run
python3 make_book.py --book_name test_books/animal_farm.epub --plan-classify all

# Tweaking the prompt
python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template_sample.txt
# or
python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template.json
# or
python3 make_book.py --book_name test_books/animal_farm.epub --prompt "Please translate \`{text}\` to {language}"

# translate txt file
python3 make_book.py --book_name test_books/the_little_prince.txt --test --language zh-hans
# aggregated translation txt file
python3 make_book.py --book_name test_books/the_little_prince.txt --test --batch_size 20

# Using Caiyun model to translate
# (the api currently only support: simplified chinese <-> english, simplified chinese <-> japanese)
# the official Caiyun has provided a test token (3975l6lr5pcbvidl6jl2)
# you can apply your own token by following this tutorial(https://bobtranslate.com/service/translate/caiyun.html)
python3 make_book.py --api_format caiyun --key 3975l6lr5pcbvidl6jl2 --book_name test_books/animal_farm.epub


# Set env BBM_CAIYUN_API_KEY to leave out --key
export BBM_CAIYUN_API_KEY=${your_api_key}

More understandable example

python3 make_book.py --book_name 'animal_farm.epub' --key sk-XXXXX --api_base 'https://xxxxx/v1' --use_context session

# Or python3 is not in your PATH
python make_book.py --book_name 'animal_farm.epub' --key sk-XXXXX --api_base 'https://xxxxx/v1' --use_context session

Microsoft Azure Endpoints

python3 make_book.py --book_name 'animal_farm.epub' --key XXXXX --api_base 'https://example-endpoint.openai.azure.com/openai/v1' --model 'deployment-name' --use_context session

# Or python3 is not in your PATH
python make_book.py --book_name 'animal_farm.epub' --key XXXXX --api_base 'https://example-endpoint.openai.azure.com/openai/v1' --model 'deployment-name' --use_context session

Features

Plan mode

An EPUB is translated through a plan by default: the book is split into units, the model decides by tag signature what to translate, so verse, lists and table cells are not missed, and neighbouring units share one request. --plan-classify chooses who decides: auto (the default), agent (you or your coding agent, through the plan file), all or none.

# preview what would be translated and what skipped (no key needed)
python3 make_book.py --book_name my_book.epub --plan-dry-run
# decide the plan yourself or with a coding agent, then rerun the same command to translate
python3 make_book.py --book_name my_book.epub --key ${key} --plan-classify agent

--plan-dry-run honours --only_filelist / --exclude_filelist. --classify-model lets another model classify, jev for the Jev classifier; --classify-base-url, --classify-key and --classify-min-confidence go with it. More: Plan mode, Recommended settings for EPUB.

Session mode

--use_context session keeps one conversation for the whole book, so names and style stay consistent. The history is re-read at the cache price and, once it reaches --context-compact-at (default 8192 tokens), compacted into a short handoff report; --no-context-compact starts the next window empty instead. Best on endpoints with prompt caching. More: Session mode.

PDF to bilingual EPUB

--to-epub turns a PDF into a reflowable bilingual EPUB with a table of contents: every paragraph followed by its translation, figures and display formulas kept as pictures. It needs the PDF extra, installed from a clone, and Pandoc 3.1.12 or newer; see Installing the PDF extra.

pip install ".[pdf]"
# two pages first; check the headings in paper_pages-1-2_book/source.md
python3 make_book.py --book_name paper.pdf --to-epub --pages 1-2 --key ${key} --use_context session
# then the whole file
python3 make_book.py --book_name paper.pdf --to-epub --key ${key} --use_context session

Scans (OCR)

--pdf-ocr reads pages that have no text layer. --ocr-lang names the languages to read (iso:zh, iso:ja, …), --ocr-engine picks the engine (auto, rapidocr, ocrmac, easyocr, tesseract), and --ocr-replace-layer reads every page again when the embedded text is wrong. More: Which OCR engine.

python3 make_book.py --book_name scan.pdf --to-epub --pdf-ocr --ocr-lang iso:zh --key ${key}

Datalab instead of the local models

If you already have a Datalab key, --pdf-parser datalab sends the PDF to the hosted Datalab Convert API instead of running docling's models (set DATALAB_API_KEY; billed per page). It reads scanned pages, equations (as LaTeX, shown as MathML in the EPUB) and figures itself, so the OCR, device and formula options do not apply. A Markdown file Datalab already wrote can be passed to --to-epub directly.

python3 make_book.py --book_name scan.pdf --to-epub --pdf-parser datalab --pages 1-2 --api_format anthropic --model claude-sonnet-5-5 --key ${key} --batch-api

Pages, figures and formulas

--pages 12-30 (or 1,3,5-7) translates only those pages, into paper_pages-12-30_bilingual.epub. Figures are drawn at 200 DPI; --pdf-image-dpi 300 sharpens tiny labels. Display formulas are kept as pictures; --no-formula-images turns that off.

Layout and hardware

--img-model MODEL shows each page to a vision model that corrects what the layout detector got wrong, such as headings, captions and code; --img-base-url and --img-key point it at another endpoint. --device picks where the extraction models run (auto, cpu, cuda, mps, xpu).

More: PDF to bilingual EPUB, Recommended settings for PDF.

Docker

You can use Docker if you don't want to deal with setting up the environment. Prebuilt images are published to GitHub Container Registry on every merge to main (as latest) and on every release tag:

docker pull ghcr.io/yihong0618/bilingual_book_maker:latest

Mount the folder containing your book at /book and pass the usual flags — the container accepts every make_book.py option, and the translated book is written back into the same folder:

# Linux / macOS
export folder_path=/path/to/your/books
export book_name=animal_farm.epub
export openai_key=sk-XXX
export language=zh-hans   # see the language list in book_maker/utils.py

docker run --rm -v "${folder_path}":/book ghcr.io/yihong0618/bilingual_book_maker:latest --book_name "/book/${book_name}" --key "${openai_key}" --language "${language}"

# Windows PowerShell
$folder_path="C:\Users\user\mybook"
$book_name="animal_farm.epub"
$openai_key="sk-xxx"
$language="zh-hans"

docker run --rm -v ${folder_path}:/book ghcr.io/yihong0618/bilingual_book_maker:latest --book_name "/book/$book_name" --key $openai_key --language $language

For example, a quick test needing no key at all, over the free Google route:

docker run --rm -v /home/user/my_books:/book ghcr.io/yihong0618/bilingual_book_maker:latest --book_name /book/animal_farm.epub --api_format google --test --test_num 1 --language zh-hant

The container runs as root, so writing into the mounted folder always works; on Linux the files it writes there belong to root (chown them afterwards, or add --user $(id -u)). API keys can also be passed as environment variables (-e OPENAI_API_KEY=sk-XXX) instead of --key.

The pdf tag adds Pandoc and the PDF packages for --to-epub, and runs to several gigabytes:

docker run --rm -v "${folder_path}":/book -v bbm-models:/root/.cache ghcr.io/yihong0618/bilingual_book_maker:pdf --book_name /book/paper.pdf --to-epub --key "${openai_key}" --use_context session

For a GPU, find your machine:

• Linux with an NVIDIA card: the pdf-cuda tag; install the NVIDIA Container Toolkit and add --gpus all.
• Windows with an NVIDIA card: the same pdf-cuda tag, through Docker Desktop's WSL2 backend.
• Mac (Apple silicon): Docker cannot reach the GPU; install the tool natively instead.
• arm64 Linux with an NVIDIA card: the pdf tag, on the processor (pdf-cuda is amd64 only).

More: Docker.

To build the image yourself instead of pulling:

docker build --tag bilingual_book_maker .
docker run --rm -v /path/to/your/books:/book bilingual_book_maker --book_name /book/animal_farm.epub --key sk-XXX --language zh-hans

Notes

1. API token from free trial has limit. If you want to speed up the process, consider paying for the service or use multiple OpenAI tokens
2. PR is welcome

Thanks

• @yetone

Contribution

• Any issues or PRs are welcome.
• TODOs in the issue can also be selected.
• Please run black make_book.py² before submitting the code.

Others better

• 书译 BookTranslator -> Book Translator

Appreciation

Thank you, that's enough.

Footnotes

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

2. https://github.com/psf/black ↩