bilingual_book_maker

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-5.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 machine-translation engines (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 [^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-5.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-5.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 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 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-5.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 and learns a glossary from its own handoff reports (--glossary-auto), so recurring names stay stable across the book — 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
  

• xAI

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format xai --key ${xai_key} --model grok-4.3 --use_context session
  

• OrcaRouter

  The OrcaRouter gateway, defaulting to its orcarouter/auto smart routing. The address comes with the route, so there is no --api_base; the key is --key or BBM_ORCAROUTER_API_KEY. --provider orcarouter reaches the same place.

  python3 make_book.py --book_name test_books/animal_farm.epub --model orcarouter --key ${orcarouter_key} --use_context session
  

  To name one model instead: --provider orcarouter --model <id>.

• Ollama

  Translate with Ollama self-hosted models. If the ollama server is not local, point --api_base http://x.x.x.x:port/v1 at it.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_base http://localhost:11434/v1 --model ${ollama_model_name} --use_context session
  

• groq

  --model is required: GroqCloud's catalogue turns over, so pick a current id from Supported Models.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format groq --key [your_key] --model llama-3.3-70b-versatile --use_context session
  

• LiteLLM

  A LiteLLM proxy, which fans out to whatever backends its own config names. --model is the name that config gives one of them. The default address is the proxy's own, on this machine; elsewhere it is --api_base.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format litellm --model ${name_in_your_litellm_config} --use_context session
  

• Codex

  Spend your ChatGPT/Codex plan. Install the Codex CLI. The default model is gpt-5.6-luna; --api_format codex --model <id> names another. One session is reused for the whole book and compacted at --context-compact-at; it runs sandboxed, with shell, MCP servers and browsing off, but hooks may still fire.

  python3 make_book.py --book_name test_books/animal_farm.epub --api_format codex --language zh-hans
  

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-5.6-luna"],
      "env_key": "OPENAI_API_KEY",
      "prices": {
        "gpt-5.6-luna": {"input": 0.20, "output": 1.20, "cached_input": 0.02}
      }
    }
  }
}

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/SRT inputs a bilingual text (or subtitle) file named ${book_name}_bilingual.txt (or _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-5.6-luna. The second column is the --api_format the id needs:

  model --api_format notes gpt-5.6-luna openai the default, at OpenAI's own address claude-sonnet-4-6 anthropic Anthropic's own a