bilingual_book_maker Documentation

Technical Documentation: yihong0618/bilingual_book_maker

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

• --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 Copy Chapter

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

  text Copy

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

• DeepL free

  shell Copy

  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.

  shell Copy

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

• Google Translate

  shell Copy

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

• Caiyun Translate

  shell Copy

  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.

  shell Copy

  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.

  shell Copy

  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

  shell Copy

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

• xAI

  shell Copy

  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.

  shell Copy

  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 .

• 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.

  shell Copy

  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.

  shell Copy

  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.

  shell Copy

  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-6-luna; --api_format codex --model 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.

  shell Copy

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

Custom API Provider Copy Chapter

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:

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 Copy Chapter

• 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 Copy Chapter

• --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 --key <key> --model , 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	any OpenAI-compatible endpoint: OpenAI itself, OpenRouter, Ollama and the rest, the address in --api_base
  anthropic	required: --key, else $BBM_API_KEY, $ANTHROPIC_API_KEY	Anthropic itself, and gateways that speak the Messages API
  gemini	required: --key, else $BBM_API_KEY, $BBM_GOOGLE_GEMINI_KEY, $GEMINI_API_KEY	the Gemini API, default gemini-flash-latest; paced by --interval
  qwen	required: --key, else $BBM_API_KEY, $BBM_QWEN_API_KEY, $DASHSCOPE_API_KEY	Qwen-MT on DashScope, default qwen-mt-turbo; reads --source_lang
  groq	required: --key, else $BBM_API_KEY, $BBM_GROQ_API_KEY, $GROQ_API_KEY	GroqCloud; --model required
  xai	required: --key, else $BBM_API_KEY, $BBM_XAI_API_KEY, $XAI_API_KEY	xAI; --model required
  litellm	none for a proxy on this machine, else --key or $LITELLM_MASTER_KEY	a LiteLLM proxy, http://localhost:4000 unless --api_base says otherwise; --model required
  codex	none: codex login (Codex CLI)	the local codex app-server sidecar on a ChatGPT/Codex plan, default gpt-6-luna
  orcarouter	required: --key or $BBM_ORCAROUTER_API_KEY	OrcaRouter
  google	none	Google Translate, free
  caiyun	required: --key or $BBM_CAIYUN_API_KEY	Caiyun
  deepl	required: --key or $BBM_DEEPL_API_KEY	DeepL (paid)
  deeplfree	none	DeepL free tier
  tencent	none	Tencent TranSmart, free
  customapi	none	a {text, source_lang, target_lang} format API

• --interval:

  Seconds to wait between requests, e.g. --interval 0.1 for 100ms. Only --api_format gemini paces itself with it; every other route ignores it. Default: 0.01.

• --test:

  Use --test option to preview the result if you haven't paid for the service. Note that there is a limit and it may take some time.

• --language:

  Set the target language: a tag (--language zh-hant), a name (--language "Traditional Chinese"), or both at once — --language "zh-hant:Traditional Chinese". The tag names the JSON structured-output field; the name is what the model is asked for. Default zh-hans. See also available tags.

• --source_lang:

  Source language. Stated, it appends a prompt line ("Translate from English"), and on --api_format qwen (whose request names a language pair) and --api_format customapi it rides in the request itself. Default: auto-detect.

• --proxy:

  Use --proxy option to specify proxy server for internet access. Enter a string such as http://127.0.0.1:7890.

• --resume:

  Use --resume option to manually resume the process after an interruption. Mutually
  exclusive with --parallel-workers.

  shell Copy

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

• --translate-tags:

  epub is made of html files. By default, we only translate contents in ``.
  Use --translate-tags to specify tags need for translation. Use comma to separate multiple tags.
  For example: --translate-tags h1,h2,h3,p,div

• --plan-classify (epub only):

  Plan mode: classify epub tags with the translating model, or with codex / claude code.

  The value decides how is translation decision of each tag made:

  • auto (default): when the book is an epub, ask the LLM what to translate. Only when the route cannot hold a conversation, and when the plan fails, translate the --translate-tags selection instead. Rows decided over a plain session appear in _plan.json with an unnamed (…) content type naming how the verdict was reached rather than what the content is.

  • none: no plan; only the --translate-tags selection — unselected, that defaults to p, most body text.

  • all: translate the whole partition, no classification.

  • model: the translating LLM judges, then translates. --plan-classify-model X picks the model that classifies.

  • agent: writes the classification plan for the book and prints instructions to paste into your coding tool for classification.
    (or you could also do it by hand). Then run the translation with --plan-classify agent again.

  • --plan-dry-run: print the per-signature table, write _plan.json, and exit. Honors --only_filelist / --exclude_filelist.

  • _plan.json: the translation plan; delete it to classify again.

  • --plan-min-coverage (default 0.5, range 0–1): plan mode aborts if the plan covers less than this fraction of the text. 0 disables the guard and values above 0.9 usually abort after classification is already paid for — both warn.

  • --max-batch-units: the most units one grouped request may carry. Raise it together with --accumulated_num for fewer, larger (cheaper) requests; lower them once the run prints degradation warnings such as the misalignment-recovery hint. Content is also bounded by the token budget (--accumulated_num).

  shell Copy

  # let the model judge which tags need translating
  python3 make_book.py --book_name my_book.epub --key ${key} --plan-classify model
  # or hand it to an agent: stops, prints instructions, then you give them to your AI
  python3 make_book.py --book_name my_book.epub --key ${key} --plan-classify agent

• --exclude-translate-tags:

  Use --exclude-translate-tags to exclude content within specified HTML tags from translation. This is useful for preserving code blocks, preformatted text, or other special content. Use comma to separate multiple tags.
  Default: sup,code.
  For example: --exclude-translate-tags code,pre

  Tip: Use --exclude-translate-tags "" to translate all content including code blocks (overrides the default exclusion).

• --api_base:

  If you want to change api_base like using Cloudflare Workers, use --api_base to support it.
  Note: the api url should be 'https://xxxx/v1'. Quotation marks are required.

• --allow_navigable_strings:

  If you want to translate strings in an e-book that aren't labeled with any tags, you can use the --allow_navigable_strings parameter. This will add the strings to the translation queue.

• --prompt:

  To tweak the prompt, use the --prompt parameter. The placeholders the user template may use are {text} (required), {language} and {crlf} (a newline, for the shapes — a JSON string, a table cell — that cannot carry one). Anything else in braces is refused before the run starts rather than raising mid-book; write {{ and }} for a literal brace. It supports a few ways to configure the prompt:

  • If you don't need to set the system role content, you can simply set it up like this: --prompt "Translate {text} to {language}." or --prompt prompt_template_sample.txt

  • If you need to set the system role content, you can use the following format: --prompt '{"user":"Translate {text} to {language}", "system": "You are a professional translator."}' or --prompt prompt_template.json.

  • A third key, style, is a standing instruction about how to write — register, tone, vocabulary. It is said once where a window starts, not repeated on every request.

  • --prompt works on every LLM route, and on srt books too — there its sections sit on top of the subtitle loader's own prompt, section by section. Replacing the user template on an srt book means saying yourself that the block number and the timeline must come back unchanged; the run warns about it. The fixed translation-service routes (google, deepl, caiyun, tencent, qwen, customapi) send text and nothing else, so they carry no prompt at all and the run says so at start.

  • A .md file is read as the PromptDown block form — the format is theirs, the reader is ours, so no extra package is installed: --prompt prompt_md.prompt.md (example at ./prompt_md.prompt.md). ## System Message, an optional ## Style, and a ## Conversation whose **User:** turn is the template. The table form of a conversation is refused. Example:

    markdown Copy

    # Translation Prompt
    
    ## System Message
    
    You are a professional translator who specializes in accurate translations.
    
    ## Conversation
    
    **User:**
    
    Please translate the following text into {language}:
    
    {text}

  • You can also set the user and system role prompt by setting environment variables: BBM_CHATGPTAPI_USER_MSG_TEMPLATE and BBM_CHATGPTAPI_SYS_MSG.

  • An example JSON file can be found at ./prompt_template.json.

• --batch_size:

  Use the --batch_size parameter to specify the number of lines for batch translation (default is 10, currently only effective for txt files).

• --accumulated_num:

  Wait for how many tokens have been accumulated before starting the translation.
  For example, if you use --accumulated_num 1600, maybe openai will output 2200 tokens and maybe 200 tokens for other messages in the system messages user messages, 1600+2200+200=4000 — on some local models that is close to the limit. You have to choose your own value, there is no way to know if the limit is reached before sending.

  In EPUB plan mode this is a per-request token budget: consecutive units of any length share one request up to N tokens. Pass 1 to turn grouping off — every unit is sent on its own.

• --use_context:

  Translate with context.

• --context_paragraph_limit:

  Use --context_paragraph_limit to set a limit on the number of context paragraphs when using the --use_context option. This applies to window mode only.

• --use_context session:

  Session mode keeps one append-only history and re-reads it at the cache
  price, so on endpoints that support caching the context can grow to about
  a chapter. When the history reaches the compact budget, the model writes
  a short handoff report (the run asks for ~300 tokens and truncates
  anything runaway), whose summary seeds the next window; _handoff.md
  holds the latest snapshot, overwritten at each compaction.
  Watch the progress bar's cached=: if it is still zero after a dozen
  requests, the endpoint may not have a cache; Ctrl+C and switch to window
  mode.

  • --context-compact-at:

    Session mode only. The estimated-token budget the whole window — the
    inherited seed included — may reach before it is compacted into a
    handoff report. Default 8192, minimum 1500: a window shorter than
    that is mostly seed and seams, so below it use window mode instead.

  • --no-context-compact:

    Session mode only. Skip the handoff report. The window still rolls over at the budget, but the next one starts empty instead of inheriting a summary. Cheaper, at the cost of continuity across the seam.

• --glossary / --terminology:

  A file of term → translation lines — one per line, # starts a note or a
  comment, plain text.
  Read by the openai- and codex-shaped routes for EPUB, Markdown, and PDF books.

  A pinned term makes the translation say what you pinned, so pin only
  renderings you can stand behind.

  • --glossary-auto on|off:

    Keep the renderings the handoff reports establish, so recurring names
    stay unified across window seams. Session mode only, and off by
    default: it relies on the model reporting its own renderings
    accurately, which takes a capable model — most runs don't need it,
    since the handoff summary already carries the recurring names.

• --parallel-workers:

  Use --parallel-workers to process EPUB chapters or Markdown batches/sections in
  parallel. Values greater than 1 spin up multiple workers (recommended: 2-4) and
  automatically fall back to sequential mode when there is only one unit of work. Other
  input loaders currently accept this shared CLI option but do not parallelize their work.

• --temperature:

  Sampling temperature for the openai and anthropic formats (the codex
  format has none). For example: --temperature 0.7.

• --block_size:

  Use --block_size to merge multiple paragraphs into one block. This may increase accuracy and speed up the process.
  For example: --block_size 5.

• --single_translate:

  Use --single_translate to output only the translated book without creating a bilingual version.

• --no_disclosure:

  An epub output adds "Translated by gpt-6-luna, 2026." below the book intro; this flag leaves it out. It also turns off the translation metadata (--translation-metadata: the model, the date and the glossary).

• --translation_style:

  Apply custom CSS to translated EPUB text, for example
  --translation_style "color: #808080; font-style: italic;".

• --translation_color:

  Shorthand for setting only the translated EPUB text color, for example
  --translation_color "#1e90ff". If --translation_style is also present, the full style
  takes precedence.

• --pdf_layout {none,top-bottom,side-by-side,all}:

  Select additional bilingual PDF outputs for PDF inputs. The default none creates no
  extra PDF; all attempts both top-bottom and side-by-side layouts. The bilingual TXT and
  EPUB outputs are unaffected.

• --to-epub, --pdf-ocr, --ocr-lang, --ocr-engine, --ocr-replace-layer, --pages, --device, --pdf-image-dpi (PDF only):

  Turn a PDF into a bilingual EPUB with a table of contents. See PDF to bilingual EPUB.

• --sentence_mode:

  Translate EPUB text sentence by sentence instead of translating each paragraph as one
  unit. It is incompatible with EPUB plan mode.

• --batch / --batch-use:

  Two-stage translation through the ChatGPT Batch API. Currently refused on EPUB
  inputs: the queue path is unreachable there, so such a run would translate live at
  full price and then submit an empty batch job instead of writing the book. Also refused
  on routes that do not implement the Batch API.

• --quiet:

  Suppress EPUB progress bars and per-paragraph source/translation echoes while retaining
  reports and errors. Recommended for log files and non-interactive agent runs.

• --retranslate "$translated_filepath" "file_name_in_epub" "start_str" "end_str":

  Retranslate from start_str to end_str's tag:

  shell Copy

  python3 "make_book.py" --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' 'This kind of thing is not a good symptom. Obviously'

  To retranslate only the tag containing start_str, pass an empty fourth argument:

  shell Copy

  python3 "make_book.py" --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' ''

• --no-thinking:

  Ask a reasoning model not to think before answering; on a paragraph of
  prose it buys nothing and costs tokens and time.

  shell Copy

  python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --no-thinking

• --extra_body:

  Pass additional JSON parameters on the routes built on the OpenAI request
  path — openai and the OpenAI-format custom providers — and on the
  anthropic route. Provide a JSON object with the desired parameters.
  Example:

  shell Copy

  python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --extra_body '{"chat_template_kwargs": {"enable_thinking": false}}'

• --extra_headers:

  Extra HTTP headers sent with every request, on the same routes. Values
  must be strings.

  shell Copy

  python3 make_book.py --book_name test_books/animal_farm.epub --key ${openrouter_key} --api_base https://openrouter.ai/api/v1 --model anthropic/claude-haiku-4.5 --extra_headers '{"HTTP-Referer": "https://example.com", "X-Title": "bilingual_book_maker"}'

  Common forms, for reference:

  shell Copy

  # openai route — disable a local/vLLM chat template's thinking block
  --extra_body '{"chat_template_kwargs": {"enable_thinking": false}}'
  # openai route (chat completions) — reasoning effort and a token ceiling,
  # neither of which has its own flag (both model-dependent)
  --extra_body '{"reasoning_effort": "low", "max_completion_tokens": 2000}'
  # anthropic route — keep extended thinking off; for translation it mostly
  # buys deviation from the source, not quality
  --extra_body '{"thinking": {"type": "disabled"}}'
  
  # OpenRouter attribution (shown on its dashboard)
  --extra_headers '{"HTTP-Referer": "https://example.com", "X-Title": "bilingual_book_maker"}'
  # a gateway's own auth or routing header (the value stays out of the logs)
  --extra_headers '{"X-API-Key": "sk-gateway-..."}'

• --provider:

  Use a custom provider defined in bbm_providers.json; --model picks a model at it. See the "Custom API Provider" section above.

• --api_key:

  Same as --key.

Examples Copy Section

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

/* Detailed source-code truncated for AI context efficiency. */

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 Copy Chapter

Plan mode Copy Section

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 Copy Section

--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 Copy Section

--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}

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 Copy Chapter

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 Copy Chapter

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[^black] before submitting the code.

Others better

• 书译 BookTranslator -> Book Translator

Appreciation Copy Chapter

Thank you, that's enough.

[^token]: You can get a token from OpenAI or Anthropic.
[^black]: https://github.com/psf/black

En Index (`docs/en/index.md`) Copy Section

bilingual book maker

bilingual book maker translates a book with a language model and writes a bilingual edition: every paragraph of the original, followed by its translation. It reads EPUB, TXT, Markdown, SRT and PDF files. It talks to OpenAI, Anthropic, Gemini, Qwen, any OpenAI-compatible endpoint (a gateway, a reseller, or a model on your own machine), a Codex subscription, and a few translation services.

pip install -U bbook_maker
export OPENAI_API_KEY=sk-...
bbook_maker --book_name my_book.epub --use_context session

That writes my_book_bilingual.epub next to my_book.epub. The default model is gpt-6-luna; the default target language is Simplified Chinese (--language zh-hans).

Where to go next Copy Chapter

• Start here: Quick start (one EPUB, one TXT, one PDF) and Installation (pip, a checkout, Docker).
• Have a coding agent? Translate with an agent: Codex or Claude Code with the repository's skill asks what you have, picks the flags and runs the tool for you.
• EPUB: the command most people need, then recommended settings for textbooks, small models and local servers; plan mode explains what happens.
• PDF: PDF to bilingual EPUB (two pages first, then the whole file), recommended settings per document type and system, and installing the PDF extra.
• Other formats: TXT, SRT and Markdown, one command each; which page for which file.
• Endpoints and models: Translating with an LLM (model, key, endpoint, retries, on-device models), session mode (one conversation for the whole book, on every format that sends context), the provider file, translation services, prompt files and environment variables.
• Evaluation: the measurements behind the parameters, one parameter per page.
• Reference: every command line option.

Use it on material you may translate Copy Chapter

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.

En Quickstart (`docs/en/quickstart.md`) Copy Section

Quick start

This page takes you from nothing to three bilingual books: an EPUB, a TXT and a PDF. It uses OpenAI's API and the default model, gpt-6-luna. Other endpoints are on Translating with an LLM.

1. Install Copy Chapter

You need Python 3.10 or newer. A virtual environment is a good idea.

pip install -U bbook_maker

After the install, the command bbook_maker is on your PATH. From a checkout of the repository, python make_book.py is the same program; see Installation.

2. Give it a key Copy Chapter

Put the key in the environment, so it stays off the command line.

export OPENAI_API_KEY=sk-...

You can pass --key instead. The lookup order is on Translating with an LLM.

3. Try it on a few paragraphs first Copy Chapter

--test translates only the first few paragraphs, so a mistake costs almost nothing. --test_num sets how many (default 10).

bbook_maker \
  --book_name test_books/animal_farm.epub \
  --test \
  --test_num 8

The sample books are in the repository's test_books/ folder. Use your own file if you installed from pip.

4. An EPUB Copy Chapter

bbook_maker \
  --book_name my_book.epub \
  --language zh-hans \
  --use_context session

• Output: my_book_bilingual.epub, beside the input.
• --use_context session keeps one conversation for the whole book, so names and terms stay consistent. See Session mode.
• The EPUB is translated through a plan by default: the tool finds every block of text (verse, tables and captions included) and asks the model which kinds are worth translating. See Plan mode.

5. A TXT file Copy Chapter

bbook_maker \
  --book_name test_books/the_little_prince.txt \
  --language zh-hans

• Output: the_little_prince_bilingual.txt, beside the input.
• Lines are sent in groups of --batch_size (default 10).

Markdown and SRT work the same way and give <name>_bilingual.md and <name>_bilingual.srt. See Formats.

6. A PDF Copy Chapter

A PDF is best turned into a bilingual EPUB with a table of contents. That route needs the PDF extra and Pandoc 3.1.12 or newer; install them first with PDF extra. Then read two pages before you pay for the whole book:

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --pages 1-2 \
  --test

Open paper_pages-1-2_book/source.md and read the headings. They become the table of contents. If they look right, run the whole file:

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --use_context session

• Output: the working folder paper_book/ (with source.md, the images, book_bilingual.md and a manifest) and a copy of the book, paper_bilingual.epub, beside the PDF.
• A scanned PDF needs --pdf-ocr. The run tells you when it does.
• Without --to-epub, a PDF takes the older route and gives paper_bilingual.txt. See PDF.

If a run stops Copy Chapter

Press Ctrl+C at any time. The run saves what it has; an EPUB run leaves my_book_bilingual_temp.epub beside the input. Run the same command again with --resume to continue:

bbook_maker \
  --book_name my_book.epub \
  --use_context session \
  --resume

A --to-epub run needs no --resume: rerun the same command and it picks up the extraction and the translation where they stopped.

Zh Index (`docs/zh/index.md`) Copy Section

bilingual book maker

bilingual book maker 用语言模型翻译一本书，生成双语版：原文的每一段后面紧跟它的译文。它能读取 EPUB、TXT、Markdown、SRT 和 PDF 文件，可以对接 OpenAI、Anthropic、Gemini、Qwen、任何 OpenAI 兼容端点（网关、转售商，或跑在你自己机器上的模型）、Codex 订阅，以及几家翻译服务。

pip install -U bbook_maker
export OPENAI_API_KEY=sk-...
bbook_maker --book_name my_book.epub --use_context session

这会在 my_book.epub 旁边生成 my_book_bilingual.epub。默认模型是 gpt-6-luna，默认目标语言是简体中文（--language zh-hans）。

接下来看哪里 Copy Chapter

• 从这里开始：快速开始（一本 EPUB、一个 TXT、一个 PDF）和安装（pip、仓库源码、Docker）。
• 有编程智能体？用智能体翻译：Codex 或 Claude Code 加载本仓库的技能后，会问清你手头有什么，替你选好参数并运行工具。
• **EPUB：**先看大多数人需要的那条命令，再看面向教材、小模型和本地服务器的推荐设置；计划模式讲解其中发生了什么。
• PDF：PDF 转双语 EPUB（先翻两页，再翻整个文件）、按文档类型和系统给出的推荐设置，以及安装 PDF 扩展。
• 其他格式：TXT、SRT 和 Markdown，各只需一条命令；另见各类文件对应的页面。
• 端点与模型：用大模型翻译（模型、key、端点、重试、本地模型）、会话模式（整本书一段对话，适用于每种会传上下文的格式）、提供方文件、翻译服务、提示词文件和环境变量。
• 评测：参数背后的测量，每个参数一页。
• 参考：全部命令行参数。

只用于你有权翻译的内容 Copy Chapter

请仅将本工具用于您有权翻译的内容——您持有必要权利的作品、许可或授权允许您翻译的作品、公有领域图书，或适用法律另行允许的使用方式。使用本工具之前，请阅读项目的 免责声明。

Zh Quickstart (`docs/zh/quickstart.md`) Copy Section

快速开始

本页带你从零开始做出三本双语书：一个 EPUB、一个 TXT 和一个 PDF。这里用的是 OpenAI 的 API 和默认模型 gpt-6-luna。其他端点见用大模型翻译。

1. 安装 Copy Chapter

需要 Python 3.10 或更新版本，最好用一个虚拟环境。

pip install -U bbook_maker

安装后，bbook_maker 命令就在 PATH 上了。在仓库源码里，python make_book.py 是同一个程序，见安装。

2. 提供 key Copy Chapter

把 key 放进环境变量，这样它就不会出现在命令行上。

export OPENAI_API_KEY=sk-...

也可以改用 --key 传入。查找顺序见用大模型翻译。

3. 先拿几段试试 Copy Chapter

--test 只翻译开头几段，出了错也几乎不花钱。--test_num 设定翻译多少段（默认 10）。

bbook_maker \
  --book_name test_books/animal_farm.epub \
  --test \
  --test_num 8

示例书放在仓库的 test_books/ 文件夹里。如果你是用 pip 安装的，就换成你自己的文件。

4. 一本 EPUB Copy Chapter

bbook_maker \
  --book_name my_book.epub \
  --language zh-hans \
  --use_context session

• 输出：my_book_bilingual.epub，就在输入文件旁边。
• --use_context session 整本书只保持一段对话，人名和术语因此前后一致。见会话模式。
• EPUB 默认按计划翻译：工具找出每一块文字（包括诗行、表格和图题），再问模型哪几类值得翻译。见计划模式。

5. 一个 TXT 文件 Copy Chapter

bbook_maker \
  --book_name test_books/the_little_prince.txt \
  --language zh-hans

• 输出：the_little_prince_bilingual.txt，就在输入文件旁边。
• 每次请求发送 --batch_size 行（默认 10）。

Markdown 和 SRT 的用法相同，分别生成 <name>_bilingual.md 和 <name>_bilingual.srt。见格式。

6. 一个 PDF Copy Chapter

PDF 最好转成带目录的双语 EPUB。这条路线需要 PDF 扩展和 Pandoc 3.1.12 或更新版本，请先按 PDF 扩展装好。然后在为整本书付费之前，先读两页：

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --pages 1-2 \
  --test

打开 paper_pages-1-2_book/source.md，看一遍标题，它们会成为目录。如果标题没问题，就翻译整个文件：

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --use_context session

• 输出：工作文件夹 paper_book/（里面有 source.md、图片、book_bilingual.md 和一份清单文件），以及 PDF 旁边的一份成书副本 paper_bilingual.epub。
• 扫描版 PDF 需要 --pdf-ocr，需要时运行会告诉你。
• 不加 --to-epub 时，PDF 走旧路线，生成 paper_bilingual.txt。见 PDF。

运行中断时 Copy Chapter

随时可以按 Ctrl+C。运行会保存已完成的部分；EPUB 运行会在输入文件旁留下 my_book_bilingual_temp.epub。加上 --resume 再运行同一条命令即可继续：

bbook_maker \
  --book_name my_book.epub \
  --use_context session \
  --resume

--to-epub 运行不需要 --resume：重新运行同一条命令，它会从提取和翻译停下的地方接着做。

En Evaluation Index (`docs/en/evaluation/index.md`) Copy Section

Measurements behind the parameters

Each page here measures one parameter: what was compared, on which sample, and the numbers that came out. The default is stated with the measurement it rests on, and each page ends with Limits: the sample size and what was not measured. Every number is copied from the measurement's own record.

Translation Copy Chapter

[Units and tokens per request](grouping-batch-size.md) Copy Section

--max-batch-units, --accumulated_num. Where grouped requests start to shift translations into the wrong slot (measured onset: 64 units), and the cost of the retry overhead at each size. Default 16 units and 1200 to 1600 tokens per request; 8 units and 800 tokens without a strict schema.

[Session compact budget](session-compact-budget.md) Copy Section

--context-compact-at. Session cost at 4096 and 8192 over 300 units, compactions counted. Default 8192, chosen for continuity on local models; 4096 used fewer tokens.

[Jev as the plan classifier](plan-classifier-jev.md) Copy Section

--classify-model, --classify-min-confidence. TypeSafe's Jev against gpt-5.6-luna on the 31 signatures of one book (27 of 31 agree), Jev's prompt tokens before and after the lean requests, and the confidence gate measured over 662 signatures in 45 EPUBs (0.95). Default: the translating model.

PDF to EPUB Copy Chapter

[OCR engines on scanned pages](pdf-ocr-engines.md) Copy Section

--ocr-engine. rapidocr, ocrmac, easyocr and tesseract on the same 20 scanned pages, character error rate and time per page, on the CPU. tesseract and ocrmac for English, rapidocr for simplified Chinese, ocrmac or rapidocr for traditional. Default auto.

[Region roles with an image model](pdf-structure-llm-roles.md) Copy Section

--img-model. 123 structure faults on 85 pages, and which of them a vision model relabelling regions fixes (40 of 66 wrong labels) and which it does not (running headers, shattered OCR pages). About 3,000 prompt tokens a page. Off unless a model is named.

Zh Evaluation Index (`docs/zh/evaluation/index.md`) Copy Section

参数背后的测量

这里每一页测量一个参数：比较了什么、用的是哪个样本、得出了哪些数字。默认值与它所依据的测量一起给出，每页最后是“局限”：样本规模，以及没有测量的内容。每个数字都照抄自该测量自己的记录。

翻译 Copy Chapter

[每次请求的单元数与 token 数](grouping-batch-size.md) Copy Section

--max-batch-units、--accumulated_num。合并请求从哪里开始把译文错放到别的位置（测得的起点：64 个单元），以及每种大小下重试开销的代价。默认每个请求 16 个单元、1200 到 1600 token；没有严格 schema 时为 8 个单元、800 token。

[会话压缩预算](session-compact-budget.md) Copy Section

--context-compact-at。300 个单元上 4096 与 8192 两档的会话成本，并统计了压缩次数。默认 8192，是为本地模型上的连续性而选；4096 用的 token 更少。

[用 Jev 做计划分类器](plan-classifier-jev.md) Copy Section

--classify-model、--classify-min-confidence。TypeSafe 的 Jev 与 gpt-5.6-luna 在一本书的 31 个签名上的对比（31 个中有 27 个一致），精简请求前后 Jev 的提示 token，以及在 45 本 EPUB 的 662 个签名上测得的置信度闸门（0.95）。默认：翻译模型。

PDF 转 EPUB Copy Chapter

[扫描页上的 OCR 引擎](pdf-ocr-engines.md) Copy Section

--ocr-engine。rapidocr、ocrmac、easyocr 和 tesseract 在同样 20 张扫描页上的字符错误率和每页耗时，均在 CPU 上。英文用 tesseract 和 ocrmac，简体中文用 rapidocr，繁体用 ocrmac 或 rapidocr。默认 auto。

[用图像模型判定区域角色](pdf-structure-llm-roles.md) Copy Section

--img-model。85 页上的 123 个结构错误，其中哪些能靠视觉模型重新标注区域修正（66 个错误标签中的 40 个），哪些不能（页眉、支离破碎的 OCR 页面）。每页约 3,000 个提示 token。除非指定模型，否则关闭。

En Agent Skill (`docs/en/agent-skill.md`) Copy Section

Translate with an agent

You have a book and want it translated well. The shortest path is to hand it to a coding agent that carries this repository's bbm-plan skill. The agent asks what you have, picks the flags, shows you the command and the cost, runs the tool quietly, and hands back the bilingual book. You are never asked to learn a flag.

What you need Copy Chapter

• A checkout of this repository. The skill runs make_book.py from the repository root, so a pip install bbook_maker alone is not enough:

  bash Copy

  git clone https://github.com/yihong0618/bilingual_book_maker.git
  cd bilingual_book_maker
  pip install -r requirements.txt   # pip install ".[pdf]" if you have PDFs

• Credentials for the model you want: an API key in .env or the environment, a model on your own machine, or a ChatGPT plan through the codex route. The agent asks which; see Translating with an LLM for what each needs.

• A coding agent that reads skills: Codex, Claude Code, or any agent the skills CLI installs into.

Codex Copy Chapter

Codex reads .agents/skills/ from the repository, so nothing is installed. Start codex in the checkout and describe the job, or name the skill:

$bbm-plan translate ~/Books/my_book.epub to Japanese

Claude Code and other agents Copy Chapter

Install the skill once. The command finds the agents on your machine and asks which to install into:

npx skills add yihong0618/bilingual_book_maker --skill bbm-plan

Then start the agent in the checkout and describe the job. In Claude Code the skill also answers to its name:

/bbm-plan translate ~/Books/my_book.epub to Japanese

What the agent does Copy Chapter

1. Asks what you have. The route (a key, a local model, a ChatGPT plan), the target language, a prompt file if you keep one, and anything you want changed from the defaults. Bilingual output is assumed: every original paragraph followed by its translation. Say "just the Chinese" if you want the translation alone.
2. Probes the endpoint with a request costing less than a cent, before anything is paid for.
3. States the command, one line per flag with the reason, the checkpoint you will see, and whose allowance it spends. Then it waits for your approval.
4. Follows the flow for the file.
   • An EPUB goes through plan mode: the tool partitions the book, the agent itself decides what a running head, a page number or a footnote marker is against the real samples, and shows you the plan before the full run.
   • A PDF becomes a bilingual EPUB: two pages first, the agent reads what came out, then the whole file.
   • TXT, SRT and Markdown take one command each.
5. Runs quietly, logging to run.log, and resumes where it stopped after a crash or a new session. Everything it needs is on disk, nothing lives only in the conversation.
6. Delivers the _bilingual file next to your book.

Reading the skill Copy Chapter

The skill is the router .agents/skills/bbm-plan/SKILL.md plus one reference file per flow (route setup, EPUB plan mode, the PDF route, plain formats, prompt files, providers), loaded only when that step runs. Read it on GitHub: .agents/skills/bbm-plan. It points at the same pages as this wiki for anything it does not spell out.

En Book Source (`docs/en/book_source.md`) Copy Section

Which page for which file

The file's extension picks how it is read. Find yours:

A PromptDown .md file is a prompt, not a book: it goes to --prompt, and a Markdown book goes to --book_name.

An EPUB without a plan Copy Chapter

If you want only chosen tags translated, turn the plan off and name the tags:

bbook_maker --book_name test_books/animal_farm.epub --plan-classify none --translate-tags div,p

If a book keeps text outside any tag, --allow_navigable_strings adds it too. A plan already covers both, so these are for books where you want exact control. A well-formed EPUB gives better results either way.

En Cmd (`docs/en/cmd.md`) Copy Section

Command Line Options

book_maker/cli.py and python3 make_book.py --help are the runtime source of truth.
The inventory below is checked against every long option registered with argparse; the
sections after it provide additional notes for selected workflows.

Complete option inventory Copy Chapter

Input, scope, and output Copy Section

EPUB plan mode Copy Section

Translation and execution Copy Section

Endpoint and credentials Copy Section

A route is an endpoint, not a model name.

A gateway that serves Claude models speaks the OpenAI shape, and a gateway
--api_base is taken to be that shape. The anthropic format is inferred only
on Anthropic's own host, or from a claude model id with no --api_base. A
gateway asked for the anthropic shape it does not serve answers 404, and the
run stops naming --api_format openai as the fix.

Key lookup order: --key (--api_key is the same flag), then BBM_API_KEY,
then the format's own: OPENAI_API_KEY, ANTHROPIC_API_KEY,
BBM_GOOGLE_GEMINI_KEY, BBM_QWEN_API_KEY, BBM_GROQ_API_KEY,
BBM_XAI_API_KEY, BBM_CAIYUN_API_KEY, BBM_DEEPL_API_KEY (each with the
vendor's own conventional variable after it). Endpoints on localhost need no
key.

The old --model preset names, the per-vendor --*_key flags,
--ollama_model and --deployment_id are no longer in the parser, but old
command lines still run: book_maker/legacy_cli.py rewrites
them into the flags above before the run starts and prints each rewrite. The
table is in Migrating from the old flags. The old
per-vendor key variables (BBM_GROQ_API_KEY, BBM_GOOGLE_GEMINI_KEY, …) are
still read for the route that used them.

Do not put secrets directly on a shared command line. Environment variables are safer for
agent and CI use. The CLI does not load .env files itself: export the variables first,
or source a local git-ignored file before running, for example
set -a; source .env; set +a; bbook_maker ....

Test translate Copy Chapter

--test

Use this option to preview the result if you haven't paid for the service or just want to test. Note that there is a limit and it may take some time.

bbook_maker --book_name test_books/Lex_Fridman_episode_322.srt --key ${openai_key} --model gpt-5-mini  --test

bbook_maker --book_name test_books/animal_farm.epub --key ${openai_key} --model gpt-5-mini  --test --language zh-hans

--test_num <TEST_NUM>

Use this option to set how many paragraph you want to translate for testing. Default is 10.

Resume Copy Chapter

--resume

Use this option to manually resume the process after an interruption.

Retranslate (epub only) Copy Chapter

--retranslate <file_name_in_epub> <start_str> <end_str>

If a file in an EPUB is not translated well, this re-translates part of it separately.
Argparse requires all four values. Use an empty end_str to retranslate only the starting
tag; an empty file_name_in_epub enables automatic filename lookup.

• Retranslate from start_str to end_str's tag:

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' 'This kind of thing is not a good symptom. Obviously'

• Retranslate the start_str tag (empty fourth value):

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' ''

• Retranslate the start_str tag and auto-find the filename (empty second and fourth values):

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' '' 'in spite of the present book shortage which' ''

Warning:

It deletes from the tag at start_str of the finished book to the next tag at end_str, and then re-translates.

Therefore, make sure the tag after end_str is translated content. When end_str is an empty string, the tag after start_str is used. There can be missing translations between the two strings, but a non-translated end boundary will cause problems.

Customize output style (epub only) Copy Chapter

--translation_style

Support changing the output style of epub files.

bbook_maker --book_name test_books/animal_farm.epub --translation_style "color: #4a4a4a; font-style: normal; background-color: #f7f7f7; padding: 5px; margin: 10px 0; border-radius: 5px;"

Proxy Copy Chapter

--proxy

Use this option to specify proxy server for internet access. Enter a string such as http://127.0.0.1:7890 .

API base Copy Chapter

--api_base <API_BASE_URL>

If you want to change api_base like using Cloudflare Workers, use this option to support it.

bbook_maker --book_name 'animal_farm.epub' --key sk-XXXXX --model gpt-5-mini --api_base 'https://xxxxx/v1'

Note: the api url should be 'https://xxxx/v1'. Quotation marks are required.

Microsoft Azure Endpoints Copy Chapter

Azure has no flag of its own. Point --api_base at the deployment's
OpenAI-compatible URL and name the deployment in --model:

bbook_maker --book_name 'animal_farm.epub' --key XXXXX --api_base 'https://example-endpoint.openai.azure.com/openai/v1' --model 'deployment-name'

Batch size (TXT, Markdown, PDF text route) Copy Chapter

--batch_size

Use this parameter to specify the number of lines for batch translation. Default is 10. Read by the TXT, Markdown and PDF (text route) loaders; EPUB uses --accumulated_num.

python3 make_book.py --book_name test_books/the_little_prince.txt --test --batch_size 20

Accumulated Num Copy Chapter

--accumulated_num <ACCUMULATED_NUM>

Wait for how many tokens have been accumulated before starting the translation. gpt3.5 limits the total_token to 4090.

In EPUB plan mode you rarely need it: the run derives a per-request budget (1200 with the stock prompts, 800 on an endpoint without a strict schema) and prints it. See the --accumulated_num row above and Units and tokens per request.

For example, if you use --accumulated_num 1600, maybe openai will
output 2200 tokens and maybe 200 tokens for other messages in the system messages user messages. 1600+2200+200=4000, so you are close to the limit.

You have to choose your own
value, there is no way to tell if the limit is reached before sending request.

En Disclaimer (`docs/en/disclaimer.md`) Copy Section

Disclaimer

bilingual_book_maker helps users create multilingual versions of books and other documents.

1. Use only material you are entitled to translate. This includes works for which you hold the necessary rights, works whose license or the rights holder's permission allows your intended use, works in the public domain under applicable law, and uses otherwise permitted by applicable law. Owning or buying a copy does not itself grant translation rights.

2. Check translation and distribution rights separately. Translation is generally an adaptation (a derivative work). Personal use is not automatically exempt from copyright restrictions. If you share a translation, ensure that your license, permission, or applicable law also allows distribution of everything included in the output, including any original text and images. The same license or permission may cover both translation and distribution. For Creative Commons works, check the specific license and version, including attribution, NonCommercial, ShareAlike, and NoDerivatives conditions where applicable. For example, NoDerivatives licenses do not authorize public sharing of translations. Public-domain status varies by jurisdiction; modern translations, editorial contributions, forewords, and illustrations may be protected separately from an older original.

3. The MIT license does not license book content. The project's MIT license covers its software and associated documentation; it grants no rights to input books or other third-party content and does not automatically apply to generated files. Use of the output remains subject to applicable law and any relevant licenses or permissions. The tool does not determine copyright ownership or verify that your intended use is permitted.

4. Preservation is not rights verification. For EPUB output, the tool carries over source attribution and rights metadata where it can. This does not establish that translation or distribution is permitted. Check the output and retain or supply attribution, copyright notices, license information, and indications of changes as required by the applicable license or permission.

5. No warranty; limitation of liability. The software is provided “as is,” without warranty, as set out in the project's MIT license. To the extent permitted by applicable law, the authors and copyright holders disclaim liability arising from use of the software, as set out in that license.

For questions or suggestions about the project, please open an issue.

免责声明

bilingual_book_maker 帮助用户制作图书及其他文档的多语言版本。

1. 请仅翻译您有权翻译的内容。 这包括您持有必要权利的作品、许可协议或权利人授权允许您按预期方式使用的作品、依据适用法律已进入公有领域的作品，以及适用法律另行允许的使用情形。持有或购买一本书或一个副本，本身并不授予翻译权。

2. 分别核实翻译和分发的权利依据。 翻译通常属于改编（演绎作品）。个人使用并不自动免受著作权限制。如果您分享译本，请确认许可协议、授权或适用法律也允许分发输出文件中包含的全部内容，包括原文和图片。同一许可协议或授权可以同时涵盖翻译与分发。使用知识共享（CC）许可的作品时，请核实具体许可及版本，包括其中适用的署名、非商业性使用、相同方式共享和禁止演绎等条件。例如，禁止演绎许可不授权公开分享译本。作品是否进入公有领域因司法辖区而异；现代译本、编辑新增内容、序言及插图可能独立于古旧原文受到保护。

3. MIT 许可证不为图书内容授予许可。 本项目的 MIT 许可证覆盖软件及随附文档；它不授予输入图书或其他第三方内容的任何权利，也不会自动适用于生成的文件。输出内容的使用仍须遵守适用法律及相关许可或授权。工具不会判定著作权归属，也不会核实您的预期使用方式是否获准。

4. 保留信息不等于核实权利。 生成 EPUB 时，工具会尽量保留源图书的署名与权利元数据。这并不代表翻译或分发已获许可。请检查输出内容，并按适用许可或授权的要求，保留或补充署名、版权声明、许可信息及修改说明。

5. 不提供担保；责任限制。 软件按本项目 MIT 许可证的规定“按原样”提供，不附带任何担保。在适用法律允许的范围内，作者及著作权人按该许可证的规定，不承担因使用软件而产生的责任。

如对项目有问题或建议，请通过 issue 联系我们。

En Docker (`docs/en/docker.md`) Copy Section

Docker

Use Docker if you do not want to set up Python yourself. Images are published to the GitHub Container Registry on every merge to main and on every release tag. The container runs python make_book.py, so every flag on this site works unchanged.

Images and tags Copy Chapter

There are three images, built from one Dockerfile.

docker pull ghcr.io/yihong0618/bilingual_book_maker:latest

Mounts Copy Chapter

• Your book folder at /book. Pass the book as /book/<file>. The translated book is written back into the same folder.
• A named volume at /root/.cache (the pdf and pdf-cuda images). The docling models download there on the first --to-epub run, about 500 MB. Without the volume every run downloads them again.

The container runs as root, so writing into the mounted folder always works. On Linux the files it writes belong to root: chown them afterwards, or add --user $(id -u).

Pass the key as an environment variable rather than on the command line: -e OPENAI_API_KEY.

An EPUB, per system Copy Chapter

=== "Linux / macOS"

```bash
docker run --rm \
  -v "$PWD":/book \
  -e OPENAI_API_KEY \
  ghcr.io/yihong0618/bilingual_book_maker:latest \
  --book_name /book/my_book.epub \
  --language zh-hans \
  --use_context session
```

=== "Windows PowerShell"

```powershell
docker run --rm `
  -v "${PWD}:/book" `
  -e OPENAI_API_KEY `
  ghcr.io/yihong0618/bilingual_book_maker:latest `
  --book_name /book/my_book.epub `
  --language zh-hans `
  --use_context session
```

A test that needs no key at all, over the free Google route:

docker run --rm \
  -v "$PWD":/book \
  ghcr.io/yihong0618/bilingual_book_maker:latest \
  --book_name /book/animal_farm.epub \
  --api_format google \
  --test \
  --test_num 1 \
  --language zh-hant

A PDF, per system Copy Chapter

The latest image has no Pandoc and no PDF packages, so it cannot run --to-epub. With an NVIDIA card use the pdf-cuda tag; everywhere else use pdf.

=== "Linux with NVIDIA"

Install the NVIDIA driver and the NVIDIA Container Toolkit on the host. Nothing else: the image carries the CUDA runtime.

```bash
docker run --rm --gpus all \
  -v "$PWD":/book \
  -v bbm-models:/root/.cache \
  -e OPENAI_API_KEY \
  ghcr.io/yihong0618/bilingual_book_maker:pdf-cuda \
  --book_name /book/paper.pdf \
  --to-epub \
  --use_context session
```

=== "Windows with NVIDIA"

Use Docker Desktop on the **WSL2 backend**. Install the WSL-capable NVIDIA driver on Windows itself, not inside WSL. Windows-containers mode cannot reach the GPU.

```powershell
docker run --rm --gpus all `
  -v "${PWD}:/book" `
  -v bbm-models:/root/.cache `
  -e OPENAI_API_KEY `
  ghcr.io/yihong0618/bilingual_book_maker:pdf-cuda `
  --book_name /book/paper.pdf `
  --to-epub `
  --use_context session
```

=== "CPU only"

The `pdf` image carries PyTorch's CPU build, for amd64 and arm64. `--device cpu` skips the accelerator detection. The output is the same as on a GPU; it is slower.

```bash
docker run --rm \
  -v "$PWD":/book \
  -v bbm-models:/root/.cache \
  -e OPENAI_API_KEY \
  ghcr.io/yihong0618/bilingual_book_maker:pdf \
  --book_name /book/paper.pdf \
  --to-epub \
  --device cpu \
  --use_context session
```

=== "macOS"

The container is CPU-only whatever you pass: Docker runs a Linux VM that cannot see Metal. The `pdf` image runs natively on Apple silicon (arm64). The [native install](installation-pdf.md) is faster there (MPS).

```bash
docker run --rm \
  -v "$PWD":/book \
  -v bbm-models:/root/.cache \
  -e OPENAI_API_KEY \
  ghcr.io/yihong0618/bilingual_book_maker:pdf \
  --book_name /book/paper.pdf \
  --to-epub \
  --device cpu \
  --use_context session
```

An NVIDIA card on arm64 Copy Chapter

pdf-cuda is built for amd64 only: the official PyTorch CUDA image it starts from is published for nothing else. On an arm64 Linux host with a card (GH200, Jetson), pdf runs on the processor.

What is not in any image Copy Chapter

The Codex route (--api_format codex). It drives a codex binary signed in on your machine; neither the binary nor the login is in the container. Use an API route in Docker.

Build it yourself Copy Chapter

A plain build gives the small image:

docker build --tag bilingual_book_maker .

The PDF images are the pdf and pdf-cuda stages:

docker build --target pdf --tag bilingual_book_maker:pdf .
docker build --platform linux/amd64 --target pdf-cuda --tag bilingual_book_maker:pdf-cuda .

En Env Settings (`docs/en/env_settings.md`) Copy Section

Environment Settings

You can write credentials into the environment to skip --key.

API key Copy Chapter

BBM_API_KEY covers every format, so one variable is usually enough:

export BBM_API_KEY=${your_api_key}

If it is not set, each format also looks at the variable people already
export for that vendor:

google, deeplfree, tencent and customapi need no key, and neither
does an endpoint on localhost — a LiteLLM proxy there included, which is
where --api_format litellm points unless --api_base says otherwise.

The CLI does not read .env files. Export the variables first, or source a
git-ignored file before running: set -a; source .env; set +a; bbook_maker ...

A provider's own variable Copy Chapter

--provider NAME reads the endpoint from bbm_providers.json in the working
directory, else ~/.bbm/providers.json. When that entry has an env_key,
the named variable is consulted for the key ahead of BBM_API_KEY and the
fallbacks above — it names the endpoint being called, so its own key is the
right one. It is consulted only while the run still calls that endpoint: an
--api_base elsewhere, or an --api_format override on an entry that names
no base_url, moves the request to another host, and the entry's key is not
sent there. The run says so; pass --key when you meant to reuse it. The file holds the address and the variable name, never a secret.
See Endpoints, models and languages.
--model orcarouter reads BBM_ORCAROUTER_API_KEY the same way.

Classifier variables Copy Chapter

A Jev-compatible classifier reads its key only for its own host:

Through a gateway, name the key with --classify-key or a provider entry's classify_env_key.

BBM_JEV_MIN_CONFIDENCE, a number from 0 to 1, sets Jev's gate for a run without --classify-min-confidence (the flag wins): a skip below it is translated. The default is 0.95. A value that is not a number from 0 to 1 stops the run.

Old per-vendor variables Copy Chapter

The four vendor variables above are also read when an old-style command
implies that route — --model gemini consults BBM_GOOGLE_GEMINI_KEY even
though the rewritten command names the format (see Migrating from the old
flags). What they are never consulted for is a command whose
--api_base names some other endpoint: there the key must match the address,
and only BBM_API_KEY and the format's own variables apply.

Prompt overrides Copy Chapter

export BBM_CHATGPTAPI_USER_MSG_TEMPLATE=${your_prompt_template}
export BBM_CHATGPTAPI_SYS_MSG=${your_system_message}

En Installation Pdf (`docs/en/installation-pdf.md`) Copy Section

Installing the PDF extra

If you want to turn a PDF into a bilingual EPUB (--to-epub), install the PDF extra from a clone of the repository:

pip install ".[pdf]"

--to-epub reads a PDF with docling's layout and table models, so it needs more than the base install: PyTorch, the models, and Pandoc to build the EPUB. None of it is installed by default, because most people translate EPUBs and never open a PDF. No Java is needed; instructions that mention a JRE or Adoptium are out of date.

1. Get the code Copy Chapter

The route is not in the published package yet, so you install from a clone.

git clone https://github.com/yihong0618/bilingual_book_maker.git

cd bilingual_book_maker

A virtual environment is recommended.

2. Pandoc Copy Chapter

You need Pandoc 3.1.12 or newer on PATH. It builds the EPUB and its navigation. Older releases point the table of contents at files instead of headings, and the tool refuses them before the PDF is opened. The apt packages on Ubuntu 24.04 and Debian 13 are older than this, so take a release from pandoc.org/installing.html.

pandoc --version

3. The PDF extra Copy Chapter

Install the extra rather than the locked requirements files: the locked files pin exact versions of PyTorch and everything else, so they download again a torch you may already have; the extra reuses what is installed.

Which PyTorch build you get is decided by the index it comes from, not by the version. Pick your system:

=== "macOS (Apple silicon)"

```bash
pip install ".[pdf]"
```

You get MPS acceleration. There is nothing to choose.

=== "Linux with NVIDIA"

```bash
pip install ".[pdf]"
```

PyPI's Linux wheel *is* the CUDA build, so this is all you need. The CUDA Toolkit is not needed; the wheel carries the runtime.

=== "Linux, CPU only"

```bash
pip install ".[pdf]" \
    --extra-index-url https://download.pytorch.org/whl/cpu
```

Without the CPU index you get about 3.2 GB of CUDA you cannot use. With it, about 380 MB, and no `nvidia-*` packages.

=== "Windows with NVIDIA"

```bat
pip install ".[pdf]" ^
    --extra-index-url https://download.pytorch.org/whl/cu126
```

**PyPI's Windows wheel is CPU-only.** Windows CUDA builds are published only on PyTorch's own index, so the plain line leaves you on the processor, silently. `cu128` is there for newer cards and drivers. The CUDA wheel is about 2.7 GB.

You also need the NVIDIA driver. PyTorch bundles the CUDA runtime, so you do **not** need the CUDA Toolkit, but the driver is yours to install:

- Driver download: <https://www.nvidia.com/en-us/drivers/> (Game Ready or Studio both work).
- PyTorch's installer matrix, to confirm the channel for your card: <https://pytorch.org/get-started/locally/>.

Check the driver before installing PyTorch:

```bat
nvidia-smi
```

It prints the driver version and the highest CUDA version it supports. If that number is below the channel you chose (12.6 for `cu126`), update the driver. An old driver is the usual reason `torch.cuda.is_available()` says `False` on a machine that has a card.

=== "Windows, CPU only"

```bat
pip install ".[pdf]"
```

On Windows this gives you the CPU build, because that is what PyPI ships there.

Use --extra-index-url, never --index-url. --index-url replaces PyPI, and everything else this tool needs would stop resolving.

If you want exactly the versions the project tests, requirements-pdf-gpu.txt and requirements-pdf-cpu.txt are the pinned sets the Docker images install (pdf the CPU file, pdf-cuda the GPU file minus the PyTorch its base already has; pip install -r requirements-pdf-cpu.txt names the CPU index inside the file). Expect them to replace the PyTorch you have.

With uv Copy Section

uv pip install ".[pdf]"

When you want the CPU build:

uv pip install ".[pdf]" --torch-backend=cpu

4. Run it Copy Chapter

Read two pages first. --test translates only a few blocks.

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --pages 1-2 \
  --test

Then the full run:

python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --use_context session

The models (about 500 MB) download on the first run, so the first PDF takes noticeably longer than the second. The progress line keeps running while they download. They come from Hugging Face, so HF_HOME moves the cache:

export HF_HOME=/path/with/room

A scan read with --pdf-ocr downloads nothing more: the pdf extra installs rapidocr with its models, and on a Mac also Apple's engine, ocrmac, which auto picks there. Which OCR engine compares them.

Once cached, extraction needs no network. Recommended settings for PDF has the command for each kind of document.

Check what you got Copy Chapter

python -c "import torch; print(torch.__version__, torch.version.cuda)"

• A version ending in +cpu, and None: the CPU build. Correct for the CPU route.
• A CUDA version like 12.6: a CUDA build. torch.cuda.is_available() then says whether this machine can use it. False means the build has CUDA but there is no usable card, or the driver is too old.
• On Apple silicon, None is correct: MPS is not CUDA. Check it with python -c "import torch; print(torch.backends.mps.is_available())".
• On Windows with an NVIDIA card, None means you are on the CPU build, which is what PyPI ships there. Go back to step 3.

--device cuda tells these two failures apart, because they have different fixes: a CPU-only build is a reinstall; a machine without a card is not.

Installing without a clone: not yet Copy Chapter

pip install "bbook_maker[pdf]" does not install the route, and it does not fail either. pip treats an unknown extra as a warning, installs the last release without docling, and exits 0:

WARNING: bbook-maker 1.2.1 does not provide the extra 'pdf'
Successfully installed bbook-maker-1.2.1

The next PDF run refuses with the missing-extra message. Until a release carries the route, clone the repository (step 1) and install ".[pdf]" from it.

Keeping the CPU build Copy Chapter

torch==…+cpu satisfies any torch>=… requirement, so nothing forces it to be replaced. But the next pip install -U that touches PyTorch without the index will fetch the CUDA wheel and pull in about 3 GB. Make the index stick to the environment:

export PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu

Or in pip.conf / pip.ini:

[global]
extra-index-url = https://download.pytorch.org/whl/cpu

The uv equivalent is UV_TORCH_BACKEND=cpu.

Or skip all of it: Docker Copy Chapter

The pdf image tag carries Pandoc and the whole docling runtime with PyTorch's CPU build: docker pull ghcr.io/yihong0618/bilingual_book_maker:pdf. With an NVIDIA card, the pdf-cuda tag. See Docker, including why a Mac should install natively instead.

Sizes Copy Chapter

What the PDF step downloads with PyTorch 2.7.1, resolved on each platform (102 packages):

Plus ~500 MB of models on the first run, on every platform.

PyTorch is most of the variation. The rest of the tree is about 200 MB everywhere (opencv 48 MB, scipy 29 MB, rapidocr 27 MB, transformers, numpy, pandas…). The PyTorch wheel alone:

The two platforms are opposites, which is the trap: on Linux the default is CUDA and you opt out; on Windows the default is CPU and you opt in. macOS has no CUDA variant; its small PyTorch carries Metal kernels and no CUDA, and nothing is missing.

If it does not work Copy Chapter

These are the lines the tool prints, and what to do.

• reading a PDF needs the pdf extra, which is not installed. Step 3 was not done. If you ran pip install "bbook_maker[pdf]" and it said it succeeded, that is the trap described above.
• Pandoc is required for --to-epub. Install it and make sure pandoc is on PATH. Do step 2.
• … is too old for EPUB export; Pandoc 3.1.12 or newer is required Your Pandoc came from apt. Install the release from pandoc.org (step 2) and put it first on PATH; the message names the harness tools/pdf_to_book.py --pandoc PATH as the other way.
• --device cuda was asked for, but the installed PyTorch is a CPU-only build. Reinstall the extra with the CUDA build: the plain line on Linux, the cu126 index on Windows (step 3).
• --device cuda was asked for, but this machine has no cuda accelerator available. The build has CUDA; the machine or driver cannot provide it. Run nvidia-smi: no output means no driver; a CUDA version lower than your channel means the driver is too old. Otherwise use --device cpu.
• On Windows, torch.version.cuda is None although the machine has a card. The plain line was used. Reinstall naming the cu126 index (step 3).
• … selected pages have no text layer …; rerun with --pdf-ocr … The PDF is a scan. Add --pdf-ocr, and --ocr-lang if the scan is not in Chinese or English. See Recommended settings for PDF.
• In Docker, --gpus all seems ignored on an ARM machine. It is: the arm64 image has a CPU-only PyTorch. Add --platform linux/amd64.
• In Docker on a Mac, the GPU is never used. Correct and unfixable: the Linux VM cannot see Metal. Install natively (steps 1 to 4) for MPS.

En Installation (`docs/en/installation.md`) Copy Section

Installation

bilingual book maker is a Python program. It needs Python 3.10 or newer. A virtual environment keeps it apart from your other packages.

From PyPI Copy Chapter

pip install -U bbook_maker

This gives you the bbook_maker command. It translates EPUB, TXT, Markdown and SRT files, and PDFs on the older text route.

The published package does not carry the PDF-to-EPUB route yet. If you want that, install from a checkout (below) and add the PDF extra.

From a checkout Copy Chapter

Use a checkout if you want the newest code or the PDF-to-EPUB route.

git clone https://github.com/yihong0618/bilingual_book_maker.git

cd bilingual_book_maker

pip install -r requirements.txt

requirements.txt is the pinned, tested set. pip install . also works and takes whatever versions resolve today. From a checkout the command is python make_book.py, with the same flags as bbook_maker.

The PDF extra Copy Chapter

If you want to turn PDFs into bilingual EPUBs (--to-epub), add the PDF extra from the same checkout. It brings docling and PyTorch; the models (about 500 MB) download on the first run, and you also need Pandoc 3.1.12 or newer.

pip install ".[pdf]"

The extra reuses a PyTorch you already have instead of downloading a pinned one. That line is right on Apple silicon, on Linux with an NVIDIA GPU, and on Windows without one. Linux without an NVIDIA GPU adds PyTorch's CPU index, or it downloads about 3 GB of CUDA it cannot use; Windows with an NVIDIA GPU adds PyTorch's CUDA index. Installing the PDF extra has the line for every case.

Do not run pip install "bbook_maker[pdf]". The published package does not carry the route yet: pip only warns and installs the release without it.

Docker Copy Chapter

If you would rather not install Python packages, use the published image. See Docker.

Check the install Copy Chapter

bbook_maker --help

From a checkout:

python make_book.py --help

The help text is the authority on every flag. Command line options lists them in one table.

En Languages (`docs/en/languages.md`) Copy Section

Languages

--language takes any row of this table either way: the tag
(--language zh-hant) or the name (--language "traditional chinese",
case-insensitive). The tag is the mechanical half — stamped on the
inserted markup and dc:language, recorded in the translation metadata record,
and it names the structured-output reply field (zh_hant_translation).
The name is the prose half: what the model is actually asked for.

For a language this table misses, pass both halves yourself as
TAG:NAME, split on the first colon — for example
--language "ain:Ainu". The tag then drives the stamps and
field names exactly as if it were listed here; the name goes to the
model. A free-typed name matching nothing still runs — the run prints
one Note: line saying nothing will be stamped on the output.

The source language is never part of --language; --source_lang
states it when auto-detection isn't enough.

Tags Copy Chapter

Other spellings Copy Chapter

Names that are not the one printed above, accepted for the same tag.

En Llm Args (`docs/en/llm-args.md`) Copy Section

Translating with an LLM

If you have an OpenAI key, the default route needs nothing else:

export OPENAI_API_KEY=sk-...
bbook_maker --book_name my_book.epub --use_context session

This page covers the flags that decide where the requests go and what they ask for. They work the same for every input format. What each format adds is on the Formats pages.

The route: model, endpoint, format Copy Chapter

A route is an endpoint, not a model name. Three flags name it.

Examples, one per common case:

=== "OpenAI"

```bash
bbook_maker \
  --book_name my_book.epub \
  --model gpt-6-luna \
  --use_context session
```

=== "Anthropic"

```bash
bbook_maker \
  --book_name my_book.epub \
  --model claude-sonnet-4-6 \
  --use_context session
```

=== "Any OpenAI-compatible endpoint"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_base https://gateway.example.com/v1 \
  --model provider/model-id \
  --use_context session
```

=== "Gemini"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format gemini \
  --model gemini-flash-latest \
  --use_context
```

Gemini keeps its own chat history, so it takes window mode (`--use_context`), not a session. `--interval` sets the pause between requests; this is how you stay under the free tier's rate limit.

=== "Codex (ChatGPT plan)"

```bash
python make_book.py \
  --book_name my_book.epub \
  --api_format codex
```

Spends your ChatGPT plan through the [Codex CLI](https://developers.openai.com/codex/cli), which must be installed and signed in (`codex login`). It runs `gpt-6-luna`; add `--model ` for another. The thread is the context, so no `--use_context` is needed. It ignores `--api_base` and `--key`. When Codex answers that the selected model is at capacity, the run prints a `codex: … retrying in 60 s` line and asks again; that answer is usually Codex rate-limiting a network it distrusts, and another network or account helps.

A gateway that serves Claude models usually speaks the OpenAI shape. If a gateway answers 404 to the anthropic shape, the run stops and names --api_format openai as the fix.

--api_format groq, xai and litellm are the OpenAI shape at Groq, xAI and a LiteLLM proxy (http://localhost:4000). Each knows its address, so the format, a key and --model are the whole route. --model is required there.

--model orcarouter sends the run to the OrcaRouter gateway and its orcarouter/auto model. The key comes from --key or BBM_ORCAROUTER_API_KEY.

One command per vendor Copy Chapter

If your vendor is listed here, this is the whole command (the key can also come from the environment, see Keys):

/* Detailed source-code truncated for AI context efficiency. */

Translation services (Google, DeepL, Caiyun, Tencent, a custom API) are on Translation services. A vendor you use often belongs in the provider file.

Keys Copy Chapter

The key is looked up in this order:

1. --key (--api_key is the same flag). Several comma-separated keys are rotated, to go past per-key rate limits.
2. BBM_API_KEY.
3. The format's own variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, BBM_GOOGLE_GEMINI_KEY, BBM_QWEN_API_KEY, BBM_GROQ_API_KEY, BBM_XAI_API_KEY.

An endpoint on localhost needs no key. A key on the command line is visible to other users of the machine in the process list; prefer the environment. The tool does not read .env files itself. Load one first:

set -a; source .env; set +a

More variables are on Environment variables.

The provider file and extra models Copy Chapter

--provider NAME takes the route from a JSON file instead of flags: bbm_providers.json in the directory you run from, or ~/.bbm/providers.json. A name in neither falls back to the shipped bbm_providers.example.json, and the run says so.

bbook_maker \
  --book_name my_book.epub \
  --provider siliconflow \
  --use_context session

Two steps can use a model other than the translating one:

The fields, the shipped entries, which key is sent where, and Jev and Jev-compatible classifiers are on Provider file and extra models. Note that the shipped openai entry names an image model, so --provider openai turns the PDF route's image step on.

Language Copy Chapter

The prompt Copy Chapter

--prompt takes a template string, a JSON string, or a .json, .txt or .md file. It has three sections:

• user: the template. Required. It must contain {text}; {language} and {crlf} are filled in too. Any other placeholder is refused when the run starts.
• system: the system message.
• style: a note on register and voice. It is said once where a context window starts, and handed on to every window in session mode.

A bare string or a .txt file is the user template. The run prints which sections it used and where. The format is on Prompt files.

bbook_maker \
  --book_name my_book.epub \
  --prompt prompt_template.json \
  --use_context session

Test runs and resuming Copy Chapter

Always run --test once on a new endpoint. It costs almost nothing and shows you the output format and the route the run chose.

Retries: what "patient" means Copy Chapter

Many people run this tool against providers that are slow or rate-limited, where the first token or a 429 backoff can take minutes. So the tool never gives up on an error that could clear by waiting.

• A timeout, a dropped connection, a 429 or a 5xx is retried with no attempt limit. The wait starts at 1 second, doubles, and stops growing at 5 minutes.
• Every retry prints one line, so a long wait does not look like a hang:
  retrying after RateLimitError (…) — attempt 4, waiting 8s
• An error that will not clear by waiting stops the run at once: a rejected key, a permission error, a request the endpoint refuses, a model that does not exist.
• Ctrl+C always stops the run, even during a long wait. The progress is saved; rerun with --resume.

If you see the same retry line for a long time, the provider is down or rate-limiting you. The run will continue by itself when it comes back.

On-device models (Ollama, llama.cpp, LM Studio) Copy Chapter

A local model is an OpenAI-compatible endpoint on your own machine. Point --api_base at it; no key is needed.

bbook_maker \
  --book_name my_book.epub \
  --api_base http://localhost:11434/v1 \
  --model qwen3:8b \
  --use_context session

What to expect from an 8B or 16B model:

• No strict JSON schema. Most local servers do not enforce one. The run notices this with a one-request probe and switches to a delimiter format, printing a line such as doesn't apply JSON schema … using delimiter method. This is not an error.
• Smaller requests. On an endpoint without a strict schema, each request carries at most 8 units, half of the default 16, and outside session mode about 800 tokens of text. The run prints the numbers it chose. The defaults are chosen so that a small model can hold them.
• Plan classification by one word. Plan mode asks the model skip or translate for five kinds of block per turn. If the model misses the reply format twice in a row, the run asks three per turn, then one. If it still misses, classification stops and the rest is translated. Anything unreadable is treated as translate, so a weak model translates too much rather than too little. You can also hand classification to a hosted model with --classify-model and keep translating locally; see Provider file and extra models.
• Short context. Set --context-compact-at to the model's input limit (minimum 1500) so a session window never overflows it.
• Thinking models. A model that reasons before it answers can be told not to with --no-thinking. The run finds the request field the server accepts from the server's own rejections. If your server needs a field of its own, --extra_body wins, for example --extra_body '{"chat_template_kwargs": {"enable_thinking": false}}'.
• No image step. The PDF route's image step runs only on a model you name with --img-model, so a local model is never asked to read a page.

Flags to avoid on a small model:

• --glossary-auto on. It needs a model that answers with names, not prose.
• Raising --accumulated_num or --max-batch-units. Lower them instead when the run prints misaligned batches this run.
• --model_list. Each model keeps its own cache, and mixing models in one conversation hurts consistency.

If plan classification keeps failing on your model, --plan-classify all skips it and translates every block. See Plan mode.

Other request options Copy Chapter

Common --extra_body and --extra_headers values:

# openai route: turn off a local/vLLM chat template's thinking block
--extra_body '{"chat_template_kwargs": {"enable_thinking": false}}'
# openai route (chat completions): reasoning effort and a token ceiling, neither of which has a flag
--extra_body '{"reasoning_effort": "low", "max_completion_tokens": 2000}'
# anthropic route: keep extended thinking off
--extra_body '{"thinking": {"type": "disabled"}}'
# OpenRouter attribution, shown on its dashboard
--extra_headers '{"HTTP-Referer": "https://example.com", "X-Title": "bilingual_book_maker"}'
# a gateway's own auth or routing header
--extra_headers '{"X-API-Key": "sk-gateway-..."}'

En Machine Args (`docs/en/machine-args.md`) Copy Section

Translation services

These routes call a translation service: text goes in, a translation comes back. Some of these services run a language model behind their API, but none takes a prompt from this tool. They need no model and often no key. They also cannot answer a question, so everything in this tool that asks the model something is off on them.

The routes Copy Chapter

Pick one with --api_format.

Both DeepL routes send the source as English. Use them for English books.

Caiyun publishes a test token, 3975l6lr5pcbvidl6jl2, for trying the route; for your own, follow this tutorial.

Commands Copy Chapter

=== "Google"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format google \
  --language zh-hant
```

=== "DeepL"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format deepl \
  --key ${deepl_key} \
  --language ja
```

=== "DeepL free"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format deeplfree \
  --language de
```

=== "Caiyun"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format caiyun \
  --key ${caiyun_key} \
  --language zh-hans
```

=== "Tencent"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format tencent \
  --language zh-hans
```

=== "Custom API"

```bash
bbook_maker \
  --book_name my_book.epub \
  --api_format customapi \
  --api_base https://your.host/translate \
  --language ja
```

The custom API contract Copy Chapter

The tool sends one POST per paragraph to --api_base, form-encoded, with three fields: text, source_lang and target_lang. It reads the translation from the data field of the JSON answer. Each request times out after 10 seconds, and the tool waits 5 seconds between requests. --source_lang reaches your service here.

What these routes cannot do Copy Chapter

• No prompt. --prompt has no place to go; the text is sent alone.
• No session. --use_context session is refused: there is no conversation to keep.
• No plan classification by the engine itself. On an EPUB the run falls back to the --translate-tags selection (p by default), so verse or tables outside `` stay untranslated. Name an LLM classifier and the book gets a full plan while the engine translates: --classify-model gpt-6-luna (it reads OPENAI_API_KEY), or a provider entry's classify_model. This was run end to end on Google Translate. Without one, --plan-classify model is refused, and --plan-classify all still translates every block the plan finds without asking anyone. See Plan mode.
• No glossary. --glossary is read only by the OpenAI- and Codex-shaped routes; here it is ignored with a warning.
• No stated source language on google, deepl, deeplfree, caiyun and tencent. --source_lang is ignored with a warning; only customapi (and the qwen LLM route) send it.

Everything else works: --test, --resume, --single_translate, the per-format flags on the Formats pages.

Rate limits Copy Chapter

Caiyun prints will sleep 60s for the time limit when it is rate-limited, and waits. DeepL free and Tencent pause between requests on their own. The patient retry policy applies to every route.

En Migration (`docs/en/migration.md`) Copy Section

Migrating from the old flags

Commands written for the old CLI keep working. Each removed flag is rewritten
into the new flags before the run starts, and a line says what it became:

$ bbook_maker --book_name book.epub --model gpt4omini --openai_key sk-...
deprecated: --openai_key is now --key
deprecated: --model gpt4omini is now --model gpt-4o-mini

Notes:

• The old key variables still work for the route that used them:
  BBM_GROQ_API_KEY for a rewritten --model groq, BBM_GOOGLE_GEMINI_KEY
  for a rewritten --model gemini, and so on.
• Flags you pass yourself win. --model gemini --api_base https://my-gateway/v1
  keeps your gateway.
• --interval is not a legacy flag: it is still in the parser and still
  paces the gemini route, which is still a route.
• qwen-mt-turbo and qwen-mt-plus are real model ids, so a command that
  also passes --api_format is left alone and nothing is printed about it.
• The other route aliases are not model ids anywhere. --model gemini
  together with an --api_format naming a different route is refused rather
  than resolved one way or the other: honouring the format would send that
  alias's key to a host it does not belong to, and honouring the alias would
  ignore what you typed. The error names both and the two ways out.
• A rewritten command runs the model it used to run, taken from the old
  preset list, not a newer one. Some of those models have since been
  retired, and the endpoint's model check says so.
• A --model value that is not an old alias passes through as a model id,
  which is the normal case now.
• The aliases for retired OpenAI models (gpt4, gpt5mini, o1, o1mini,
  o1preview) are gone. They now pass through as model ids and the endpoint
  rejects them by name, which is the same failure one step earlier and with
  a clearer message.

En Model Lang (`docs/en/model_lang.md`) Copy Section

Endpoints, models and languages

A route is chosen by the endpoint it talks to, not by a model name. There is
no built-in model list to keep up to date: --model takes whatever id
your endpoint serves.

bbook_maker --book_name book.epub \
  --api_base https://api.openai.com/v1 --key sk-... \
  --model gpt-5-mini --language ja

Old --model commands still work — they are rewritten into these flags and
the substitution is printed. Migrating from the old flags
has the full table.

The route flags Copy Chapter

--model_list a,b rotates across several models and is also what older
commands used; name a model in one flag or the other, not both.

--api_format is one of openai (default), anthropic, gemini, qwen,
groq, xai, litellm, codex, or the fixed translation services
google, caiyun, deepl, deeplfree, tencent, customapi.

The five vendor formats each carry their own endpoint, so the format and a
key are a whole route with no --api_base to look up:

gemini and qwen are protocols of their own — Gemini's native
constrained decoding, its safety settings and chat history; Qwen-MT's
source/target language pair in place of a prompt — and --interval paces
the gemini route, which is how the free tier's rate limit is stayed under.
The other three are the OpenAI route at another address and keep everything
it has. None of the five is ever inferred from a host: name the format, or
give the vendor's OpenAI-compatible --api_base and get the openai route.

codex is not an endpoint at all: it drives a local codex app-server
sidecar and bills the run to your ChatGPT plan, so it takes no --key and no
--api_base, and --model is optional (default gpt-6-luna). It is never
inferred; name it explicitly. See Translating with an LLM.

Inference goes in this order: an explicit --api_format wins; then the
--api_base host (anthropic.com means the anthropic shape, anything else
the OpenAI shape); then, when no endpoint was named, a model id mentioning
claude or anthropic, anthropic/claude-sonnet-4-6 included.

A gateway asked for the anthropic shape it does not serve answers 404 or
405 on /v1/messages. The run stops and names the fix: rerun with
--api_format openai. On Anthropic's own host a 404 means the model does
not exist and is reported as such.

Credentials come from --key, then BBM_API_KEY, then the format's
conventional variable — see Environment settings. An
endpoint on localhost needs no key.

Named endpoints: `--provider` Copy Chapter

An endpoint used more than once can be written down instead of retyped.
bbm_providers.json in the working directory is read first, then
~/.bbm/providers.json; a project entry wins on a shared name.

{
  "nvidia": {
    "api_style": "openai",
    "base_url": "https://integrate.api.nvidia.com/v1",
    "default_models": ["moonshotai/kimi-k2-thinking"],
    "env_key": "NVIDIA_API_KEY"
  }
}

bbook_maker --book_name book.epub --provider nvidia --language ja

api_style is any --api_format that names an endpoint — openai,
anthropic, gemini, qwen, groq, xai, litellm — plus claude as
the older spelling of anthropic. Any other OpenAI-compatible host is
openai with its address in base_url. The shipped
bbm_providers.example.json has an entry for each. Explicit flags still win over the entry, and the entry's env_key travels
exactly as far as the entry's address does. Asking for another wire format
at the entry's own gateway moves nothing, so the key is still read. An
--api_base pointing somewhere else does move the run, and so does an
--api_format override on an entry with no base_url, since there the
format is what supplies the address — the key is not read for another
vendor's host, and the run says which two addresses it is comparing. Pass
--key when you meant to reuse it. default_models supplies --model when it
holds one id and --model_list when it holds several, and env_key names
the variable to read the key from; no secret goes in the file. Anything
passed explicitly wins, so --provider nvidia --model keeps that
model. An unknown name is an error naming both files.

OrcaRouter Copy Chapter

bbook_maker --book_name book.epub --model orcarouter --language ja

--model orcarouter sends the run to the OrcaRouter gateway and asks for
its smart-routing model, orcarouter/auto. It needs no --api_base, and
one you pass yourself wins. The key is read from BBM_ORCAROUTER_API_KEY
before the usual fallbacks. It is a supported route, not a legacy alias, so
nothing is rewritten. To pin one model at the gateway, name the endpoint
like any other: --api_base https://api.orcarouter.ai/v1 --model .

OpenAI-compatible endpoints Copy Chapter

Everything below is the same route with a different --api_base. Structured
output, --use_context, parallel workers, async and the Batch API are
available on all of them to the extent the endpoint itself supports them —
support is probed at runtime rather than assumed from the model name.

--use_context session also needs the endpoint to charge less for cached
prompt tokens. Watch the cached= count on the progress bar: still zero
after a dozen requests means the endpoint is not caching, and window mode
is cheaper.

bbook_maker --book_name book.epub \
  --api_base https://api.groq.com/openai/v1 --key gsk-... \
  --model llama-3.3-70b-versatile

--extra_body passes vendor-specific request fields on this route.

Anthropic Copy Chapter

bbook_maker --book_name book.epub \
  --api_base https://api.anthropic.com --key sk-ant-... \
  --model claude-sonnet-4-6 --language zh-hans

Any model id the endpoint serves is accepted. Claude uses one model per run,
so extra --model_list entries are announced and ignored rather than
silently dropped. A gateway that serves the anthropic shape from an
OpenAI-style /v1 base is handled: the trailing /v1 is trimmed, because
the SDK appends its own.

Classification through this format uses the prompt rung — the endpoint is not
asked to compile a schema.

Translation services Copy Chapter

These speak their own protocols and take no model, so naming one is an error
rather than a silent no-op.

They translate text and nothing else: no context window and no structured
output. They cannot classify an EPUB for plan mode themselves; with
--classify-model naming a model that can, an EPUB gets plan mode on these
engines too. --source_lang reaches customapi
(it goes into the request body); the other engines detect the source
themselves. (On the LLM routes the flag reaches the prompt — see
Languages below.)

Languages Copy Chapter

--language LANGUAGE sets the target language and defaults to zh-hans.
It takes a tag (zh-hant), a name ("Traditional Chinese"), or both at
once — --language "zh-hant:Traditional Chinese" — for a language the
built-in tables miss. The tag half is mechanical: stamped on the inserted
markup and dc:language, recorded in translation metadata, and it names the
structured-output field. The name half is what the model is asked for in
the prompt. A bare tag or name resolves through the tables as before; a
value matching no tag still runs, prints one Note: at startup, and
stamps nothing. The full table: Language tags and names.

bbook_maker --help
bbook_maker --book_name book.epub --api_format google --language ja

--source_lang states the source language rather than detecting it; stated,
it reaches every LLM route's prompt and the request body on
qwen/customapi. The default auto states nothing. Not every endpoint
supports every language the parser accepts.

En Prompt (`docs/en/prompt.md`) Copy Section

Tweak the prompt

To tweak the prompt, use the --prompt parameter. The placeholders the user template may use are {text} (required), {language} and {crlf} (a newline, for the shapes that cannot carry one). Anything else in braces is refused before the run starts; write {{ and }} for a literal brace. It supports a few ways to configure the prompt:

• If you don't need to set the system role content, you can simply set it up like this: --prompt "Translate {text} to {language}." or --prompt prompt_template_sample.txt

  text Copy

  # prompt_template_sample.txt
    Translate the given text to {language}. Be faithful or accurate in translation. Make the translation readable or intelligible. Be elegant or natural in translation. If the text cannot be translated, return the original text as is. Do not translate person's name. Do not add any additional text in the translation. The text to be translated is: 
    {text}

• If you need to set the system role content, you can use the following format: --prompt '{"user":"Translate {text} to {language}", "system": "You are a professional translator."}' or --prompt prompt_template.json

  text Copy

  # prompt_template.json
    {
        "system": "You are a professional book translator. Translate the given paragraphs into {language} and be accurate, faithful, and fluent. Return translated {language} text only.",
        "user": "Translate the following into {language}. Text:{crlf}{crlf}{text}",
        "style": ""
    }

• A third key, style, is a standing instruction about how to write. It is said once where a window starts — with the system message on the API routes, with the thread instructions on codex — not repeated on every request. The shipped prompt_template.json carries all three keys with style left empty: write your own voice in, or leave it blank.

• --prompt reaches every LLM route, srt books included: there its sections sit on top of the subtitle loader's own prompt, section by section, and replacing the user template means saying yourself that the block number and timeline must come back unchanged.

You can also set the user and system role prompt by setting environment variables: BBM_CHATGPTAPI_USER_MSG_TEMPLATE and BBM_CHATGPTAPI_SYS_MSG (gemini reads BBM_GEMINIAPI_USER_MSG_TEMPLATE and BBM_GEMINIAPI_SYS_MSG). --prompt outranks all of them. OPENAI_API_SYS_MSG is still read as a fallback but is deprecated; --prompt's own system message wins over it.

• A .md file is read as the PromptDown block form. The format is theirs; the reader is this repo's own, so no extra package is installed. --prompt prompt_md.prompt.md

  text Copy

  # Translation Prompt
  
    ## System Message
  
    You are a professional translator who specializes in accurate translations.
  
    ## Conversation
  
    **User:**
  
    Please translate the following text into {language}:
  
    {text}

  Three sections are read: ## System Message (## Developer Message is
  accepted as another name for it), an optional ## Style, and
  ## Conversation, whose first **User:** turn is the user template. A
  conversation written as a | Role | Content | table is refused — the
  template's newlines cannot survive a table cell.

Examples Copy Chapter

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}"

En Providers (`docs/en/providers.md`) Copy Section

Provider file and extra models

A run translates through one endpoint. Two kinds of step can use a second one:

• Classification. Plan mode asks a model which kinds of block in an EPUB are worth translating. By default that is the translating model. You can name another with --classify-model.
• Steps that look at a page image. Today there is one: on the PDF route, a vision model can correct the roles docling gives the regions of a page. It runs only when you name a model with --img-model.

You can name both on the command line or in a provider entry. This page covers the provider file, the two extra models, and which key goes where.

The provider file Copy Chapter

--provider NAME takes the route from a JSON file instead of flags. The run reads three files. A later one wins on a shared name:

1. bbm_providers.example.json, shipped next to make_book.py. The run uses it only for a name that is in neither of the other two files, and it says so every time, with the address and the key variable it used. Its FILL-ME entries are templates and are never used.
2. ~/.bbm/providers.json.
3. bbm_providers.json in the directory you run from.

{
  "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"
    }
  }
}

bbook_maker \
  --book_name my_book.epub \
  --provider siliconflow \
  --use_context session

Flags you pass yourself win over the entry.

Fields Copy Section

The spent amount is an estimate from the usage each request reports; the vendor's bill is the number that counts.

The shipped `openai` entry turns the image step on Copy Section

The example file's openai entry sets "img_model": "gpt-6-luna". So --provider openai on a PDF with --to-epub runs the region-role pass on every page by default. That also holds when you have no bbm_providers.json, because the run then falls back to the example. The pass costs about 3,000 prompt tokens per page: 43,443 prompt and 4,319 completion tokens for 12 pages in the study behind it (Region roles with an image model). To run without it, pass --img-model none, or copy the file and delete the line.

The openai-jev entry is the same openai entry plus "classify_model": "jev" with JEV_API_KEY, so --provider openai-jev translates with gpt-6-luna and classifies an EPUB's plan with Jev. The jev entry is Jev on its own: it classifies and never translates, so --provider jev is refused with a hint to use --classify-model. No other entry names an image model or a classify model.

The two extra models Copy Chapter

Where each model comes from Copy Section

The image step never falls back to the translating model. It runs only when a model is named for it, by the flag or by the entry, so no default needs a model that reads images. --img-model none turns an entry's image model off for one run.

--plan-classify-model is the old name of --classify-model. It still works and is not in --help. If you type both, --classify-model wins.

Where each model is asked Copy Section

• Without a base URL, the model is asked at the run's own endpoint, with the run's format and key.
  • An image model needs that endpoint to be OpenAI-shaped. On any other format the run stops before it starts: --img-model needs an OpenAI-compatible endpoint; … resolves to the … format.
  • A classify model works on any LLM route that can hold a conversation, the anthropic and codex routes included.
  • On a translation-service run there is no model to share an endpoint with. A classify model named without a base is then asked at the host its id implies: --classify-model gpt-6-luna goes to OpenAI.
• With --img-base-url or --classify-base-url, the model is asked there. The address must speak the OpenAI shape, or, for a classifier, the Jev protocol; anything else is refused before anything is paid for.
• A base URL without its model stops the run: --img-base-url names where --img-model is served, and no --img-model was given. (and the same for --classify-base-url).

A named classify model always gets its own client, even on the run's address, so its tokens are counted apart from the translation's.

Before the image step runs, the run checks once that the model can read a picture. If it cannot, the run says … did not read the probe image (…); image steps are skipped this run. and goes on without the step.

Which key goes where Copy Section

A key is bound to an address. It is never sent to a host it was not meant for. For the image model and the classify model, the key is found in this order:

1. --img-key or --classify-key.
2. The run's key, but only when the model is asked at the run's own address. The run's address is the one after any --api_base.
3. The entry's img_env_key or classify_env_key, but only at the address that entry names for the model: its img_base_url or classify_base_url, else the entry's base_url. An --api_base that moves the run elsewhere does not carry the entry's key with it.
4. The variable the address's format reads, as for the run (see Keys).

When none of these holds a key, the run stops and names the flag to pass.

--extra_body and --extra_headers reach the image or classify model only when it is asked at the run's own address. Headers often carry a gateway's credential, so they never travel to another host.

Examples Copy Section

Translate on a local model, and let a hosted model classify the plan and read page images:

{
  "providers": {
    "local-with-helpers": {
      "api_style": "openai",
      "base_url": "http://localhost:11434/v1",
      "default_models": ["qwen3:8b"],
      "classify_model": "gpt-6-luna",
      "classify_base_url": "https://api.openai.com/v1",
      "classify_env_key": "OPENAI_API_KEY",
      "img_model": "gpt-6-luna",
      "img_base_url": "https://api.openai.com/v1",
      "img_env_key": "OPENAI_API_KEY"
    }
  }
}

The same with flags:

bbook_maker \
  --book_name my_book.epub \
  --api_base http://localhost:11434/v1 \
  --model qwen3:8b \
  --classify-model gpt-6-luna \
  --classify-base-url https://api.openai.com/v1 \
  --classify-key "$OPENAI_API_KEY" \
  --use_context session

A local server needs no key, so the run's key is empty here; the classifier's key must be named.

Jev and Jev-compatible classifiers Copy Chapter

Jev is TypeSafe's classifier: a model built to answer typed questions, not to write. Plan mode's question for each kind of block, translate it or keep it, is that kind of question, and Jev answers a page of them in one cheap round trip. It translates nothing, so it can only be the classify model. A gateway in front of TypeSafe (Vercel's, or Cloudflare AI Gateway with TypeSafe as a custom provider) speaks the same protocol.

The commands Copy Section

For example, translating with gpt-6-luna and classifying with Jev:

bbook_maker \
  --book_name my_book.epub \
  --model gpt-6-luna \
  --classify-model jev

The rules Copy Section

• A key is read from the environment only for its own host. JEV_API_KEY and TYPESAFE_API_KEY go only to a typesafe.ai address. Anywhere else, a gateway included, name the key with --classify-key or the entry's classify_env_key.
• A Cloudflare gateway's token is read only for Cloudflare. CF_AIG_TOKEN is sent as cf-aig-authorization only to gateway.ai.cloudflare.com. With the token set and no key named, no key is sent: the gateway supplies the one it stores. On the gateway, TypeSafe is a custom provider with base URL https://api.typesafe.ai.
• A base URL that already ends in /systemone is used as it is. Any other Jev base gets /systemone added after a /v1.
• jev alone asks for TypeSafe's current model, jev-latest.

The gate: a doubtful skip is translated Copy Section

Jev returns a probability with each answer. A skip below the gate is recorded as translate, so no content is lost to a skip Jev was unsure of. A translate is taken at any probability. The gate is 0.95 on the probability of the chosen answer, measured over 662 plan signatures from 45 EPUBs against gpt-5.6-luna. At that value about nine of ten of Jev's skips become translate, and what Jev still skips is apparatus: copyright lines, line numbers, note marks, index locators. So on that corpus Jev saves little over translating everything; see Jev as the plan classifier. The plan file shows each fallback on its row: unnamed (jev verdict skip at confidence 0.61, below the gate: translate). --classify-min-confidence P (0 to 1) moves the gate for a run; BBM_JEV_MIN_CONFIDENCE does the same without the flag, and the flag wins. A lower value keeps more of Jev's skips: on the measured corpus those below 0.9 agreed with the reference 7–55% of the time, so the risk is yours.

In a provider entry Copy Section

If you want OpenAI to translate and Jev to classify, the shipped openai-jev entry already does it: --provider openai-jev. For any other pairing, write your own entry.

classify_model, classify_base_url and classify_env_key name a Jev classifier the same way the flags do:

{
  "providers": {
    "openai-with-jev": {
      "api_style": "openai",
      "default_models": ["gpt-6-luna"],
      "env_key": "OPENAI_API_KEY",
      "classify_model": "typesafe-ai/jev",
      "classify_base_url": "https://ai-gateway.vercel.sh/typesafe",
      "classify_env_key": "JEV_API_KEY"
    }
  }
}

An entry that names JEV_API_KEY for its own gateway address has named the key for that address, and it is honored. Without such an entry, the Jev variables are never sent to a gateway.

Each Jev request sends the page's candidate lines once, with one short question per signature. See Jev as the plan classifier.

What the run prints Copy Chapter

A --plan-dry-run shows where each model would be asked, without a key:

Classifier: gpt-6-luna at the openai endpoint's default host (cli)
Image model: off

The part in brackets is where the choice came from: cli, provider or run. Under --plan-classify all or agent the line reads Classifier: none (--plan-classify agent asks nothing).

At the end of the run, a model on a client of its own prints its own usage line under the translation's:

Classifier (gpt-6-luna at the endpoint's default host): tokens: in 7.6k, out 1.8k, cached 0 (3 requests)

The image model's line reads Image model (<model> at <address>): … and is printed after the extraction.

These warnings mean a flag does nothing this run:

• --img-model, --img-base-url and --img-key choose the vision model for the steps that look at a page image, and only the PDF route (--to-epub on a PDF) has one; … You named an image model on a book that is not a PDF on the --to-epub route.
• --classify-model names a classifier, and --plan-classify all translates the whole partition without classifying anything; it is ignored this run. The same for --plan-classify agent: agent mode leaves every row to your agent and asks no model.
• Nothing on this route classifies yet, so --classify-model is ignored on a … book. Only an EPUB has a classification step today.

En Session Grouping Eval (`docs/en/session_grouping_eval.md`) Copy Section

This report was split into Units and tokens per request and Session compact budget.

Zh Agent Skill (`docs/zh/agent-skill.md`) Copy Section

用智能体翻译

你有一本书，想把它翻译好。最省事的办法是交给一个带有本仓库 bbm-plan 技能的编程智能体。智能体会问清你手头有什么、选好参数，给你看命令和费用，安静地运行工具，最后交回双语书。你不需要学任何一个参数。

你需要准备 Copy Chapter

• **本仓库的源码。**技能在仓库根目录运行 make_book.py，所以只 pip install bbook_maker 是不够的：

  bash Copy

  git clone https://github.com/yihong0618/bilingual_book_maker.git
  cd bilingual_book_maker
  pip install -r requirements.txt   # pip install ".[pdf]" if you have PDFs

• 你要用的模型的凭据：放在 .env 或环境变量里的 API key、跑在你自己机器上的模型，或者经由 codex 路线使用的 ChatGPT 套餐。智能体会问你用哪一种；每种各需要什么，见用大模型翻译。

• 一个能读取技能的编程智能体：Codex、Claude Code，或者 skills CLI 能安装到的任何智能体。

Codex Copy Chapter

Codex 会从仓库读取 .agents/skills/，所以什么都不用装。在仓库目录里启动 codex，描述任务，或者直接点名技能：

$bbm-plan translate ~/Books/my_book.epub to Japanese

Claude Code 和其他智能体 Copy Chapter

先安装一次技能。这条命令会找出你机器上的智能体，并问你装到哪一个：

npx skills add yihong0618/bilingual_book_maker --skill bbm-plan

然后在仓库目录里启动智能体，描述任务。在 Claude Code 里，技能也可以直接用名字调用：

/bbm-plan translate ~/Books/my_book.epub to Japanese

智能体会做什么 Copy Chapter

1. **问清你手头有什么。**路线（key、本地模型、ChatGPT 套餐）、目标语言、你常用的提示词文件（如果有），以及你想改动的默认设置。默认输出双语：原文每段后面紧跟译文。如果只想要译文，就说“只要中文”。
2. 探测端点：在花任何钱之前，先发一个花费不到一美分的请求。
3. 说明命令：每个参数一行并附理由，告诉你会看到的检查点，以及花的是谁的额度。然后等你批准。
4. 按文件类型走对应流程。
   • EPUB 走计划模式：工具先把书切分好，智能体根据真实样本自己判断哪些是页眉、页码或脚注标记，并在完整运行之前把计划给你看。
   • PDF 转成双语 EPUB：先翻两页，智能体读过产出之后，再翻整个文件。
   • TXT、SRT 和 Markdown 各只需一条命令。
5. 安静地运行，日志写到 run.log；崩溃后或开新会话时，从停下的地方继续。它需要的一切都在磁盘上，没有任何东西只存在于对话中。
6. 交付：把 _bilingual 文件放在你的书旁边。

阅读技能内容 Copy Chapter

技能由路由文件 .agents/skills/bbm-plan/SKILL.md 加上每个流程一份参考文件组成（路线设置、EPUB 计划模式、PDF 路线、纯文本格式、提示词文件、提供方），只在运行到那一步时才加载。可以在 GitHub 上阅读：.agents/skills/bbm-plan。凡是它没有写明的内容，它指向的都是本 wiki 里的同一批页面。

Zh Book Source (`docs/zh/book_source.md`) Copy Section

各类文件对应的页面

文件的扩展名决定它怎么被读取。找到你的那一行：

PromptDown 格式的 .md 文件是提示词，不是书：它交给 --prompt，而 Markdown 格式的书交给 --book_name。

不用计划翻译 EPUB Copy Chapter

如果只想翻译指定的标签，就关掉计划并列出这些标签：

bbook_maker --book_name test_books/animal_farm.epub --plan-classify none --translate-tags div,p

如果一本书有不在任何标签里的文字，--allow_navigable_strings 会把它们也加进来。计划本来就同时覆盖这两种情况，所以这些参数是给想精确控制的书用的。无论哪种方式，结构规范的 EPUB 效果都更好。

Zh Cmd (`docs/zh/cmd.md`) Copy Section

命令行参数

运行时以 book_maker/cli.py 和 python3 make_book.py --help 为准。
下面的清单已与 argparse 注册的每个长参数逐一核对过；清单之后的各节为部分工作流提供补充说明。

完整参数清单 Copy Chapter

输入、范围与输出 Copy Section

EPUB 计划模式 Copy Section

翻译与执行 Copy Section

端点与凭据 Copy Section

路线指的是端点，而不是模型名。

提供 Claude 模型的网关说的是 OpenAI 形态，给了网关的 --api_base 时也按这种形态处理。
只有在 Anthropic 自己的主机上，或者没有 --api_base 而模型 id 含 claude 时，才会推断为 anthropic 格式。
如果向一个不提供 anthropic 形态的网关请求这种形态，它会返回 404，运行随即中止，并指出修正方法是 --api_format openai。

key 的查找顺序：--key（--api_key 是同一个参数），然后是 BBM_API_KEY，
再然后是该格式自己的变量：OPENAI_API_KEY、ANTHROPIC_API_KEY、
BBM_GOOGLE_GEMINI_KEY、BBM_QWEN_API_KEY、BBM_GROQ_API_KEY、
BBM_XAI_API_KEY、BBM_CAIYUN_API_KEY、BBM_DEEPL_API_KEY（每个之后还有该厂商惯用的变量）。
localhost 上的端点不需要 key。

旧的 --model 预设名、各厂商的 --*_key 参数、--ollama_model 和 --deployment_id 已经不在解析器里了，
但旧命令行仍然能运行：book_maker/legacy_cli.py 会在运行开始前把它们改写成上面的参数，并打印每一处改写。
对照表见从旧参数迁移。
旧的各厂商 key 变量（BBM_GROQ_API_KEY、BBM_GOOGLE_GEMINI_KEY……）在原来使用它们的路线上仍然会被读取。

不要把密钥直接写在共享的命令行上。对智能体和 CI 来说，环境变量更安全。
CLI 自己不会加载 .env 文件：请先导出变量，或者在运行前 source 一个被 git 忽略的本地文件，例如
set -a; source .env; set +a; bbook_maker ...。

测试翻译 Copy Chapter

--test

如果你还没为服务付费，或者只想试一试，可以用这个参数预览结果。注意会有限制，可能需要一些时间。

bbook_maker --book_name test_books/Lex_Fridman_episode_322.srt --key ${openai_key} --model gpt-5-mini  --test

bbook_maker --book_name test_books/animal_farm.epub --key ${openai_key} --model gpt-5-mini  --test --language zh-hans

--test_num <TEST_NUM>

用这个参数设置测试时要翻译多少段。默认是 10。

续跑 Copy Chapter

--resume

中断后，用这个参数手动继续处理。

重新翻译（仅 epub） Copy Chapter

--retranslate <file_name_in_epub> <start_str> <end_str>

如果 EPUB 中某个文件翻译得不好，可以用它单独重新翻译其中一部分。
argparse 要求四个值都给出。end_str 传空值时只重新翻译起始标签；
file_name_in_epub 传空值时会自动查找文件名。

• 从 start_str 重新翻译到 end_str 所在的标签：

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' 'This kind of thing is not a good symptom. Obviously'

• 只重新翻译 start_str 所在的标签（第四个值为空）：

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' 'index_split_002.html' 'in spite of the present book shortage which' ''

• 重新翻译 start_str 所在的标签，并自动查找文件名（第二个和第四个值为空）：

  text Copy

  bbook_maker --book_name "test_books/animal_farm.epub" --retranslate 'test_books/animal_farm_bilingual.epub' '' 'in spite of the present book shortage which' ''

警告：

它会从成书中 start_str 所在的标签开始，删到 end_str 所在的下一个标签为止，然后重新翻译。

因此，请确保 end_str 之后的那个标签是译文内容。end_str 为空字符串时，使用 start_str 之后的那个标签。两个字符串之间可以有漏译，但结束边界若不是译文就会出问题。

自定义输出样式（仅 epub） Copy Chapter

--translation_style

支持修改 epub 文件的输出样式。

bbook_maker --book_name test_books/animal_farm.epub --translation_style "color: #4a4a4a; font-style: normal; background-color: #f7f7f7; padding: 5px; margin: 10px 0; border-radius: 5px;"

代理 Copy Chapter

--proxy

用这个参数指定访问互联网的代理服务器。传入类似 http://127.0.0.1:7890 的字符串。

API 地址 Copy Chapter

--api_base <API_BASE_URL>

如果你想更换 api_base，比如使用 Cloudflare Workers，可以用这个参数。

bbook_maker --book_name 'animal_farm.epub' --key sk-XXXXX --model gpt-5-mini --api_base 'https://xxxxx/v1'

注意：api 地址应该是 'https://xxxx/v1' 这样的形式，必须加引号。

Microsoft Azure 端点 Copy Chapter

Azure 没有专门的参数。把 --api_base 指向部署的 OpenAI 兼容 URL，
并在 --model 里写上部署名：

bbook_maker --book_name 'animal_farm.epub' --key XXXXX --api_base 'https://example-endpoint.openai.azure.com/openai/v1' --model 'deployment-name'

批量大小（TXT、Markdown、PDF 纯文本路线） Copy Chapter

--batch_size

用这个参数指定批量翻译的行数。默认是 10。由 TXT、Markdown 和 PDF（纯文本路线）加载器读取；EPUB 用的是 --accumulated_num。

python3 make_book.py --book_name test_books/the_little_prince.txt --test --batch_size 20

累积 token 数 Copy Chapter

--accumulated_num <ACCUMULATED_NUM>

累积到多少个 token 之后才开始翻译。gpt3.5 把 total_token 限制在 4090。

在 EPUB 计划模式下你很少需要它：运行会自动推算每个请求的预算（用自带提示词时为 1200，在不支持严格 schema 的端点上为 800），并把它打印出来。见上面 --accumulated_num 那一行和每次请求的单元数与 token 数。

例如，如果你用 --accumulated_num 1600，openai 可能会输出 2200 个 token，
system 消息和 user 消息里的其他内容可能还要 200 个 token。1600+2200+200=4000，已经接近上限了。

你得自己选一个合适的值，在发送请求之前无法判断是否已经达到上限。

Zh Disclaimer (`docs/zh/disclaimer.md`) Copy Section

免责声明

bilingual_book_maker 帮助用户制作图书及其他文档的多语言版本。

1. 请仅翻译您有权翻译的内容。 这包括您持有必要权利的作品、许可协议或权利人授权允许您按预期方式使用的作品、依据适用法律已进入公有领域的作品，以及适用法律另行允许的使用情形。持有或购买一本书或一个副本，本身并不授予翻译权。

2. 分别核实翻译和分发的权利依据。 翻译通常属于改编（演绎作品）。个人使用并不自动免受著作权限制。如果您分享译本，请确认许可协议、授权或适用法律也允许分发输出文件中包含的全部内容，包括原文和图片。同一许可协议或授权可以同时涵盖翻译与分发。使用知识共享（CC）许可的作品时，请核实具体许可及版本，包括其中适用的署名、非商业性使用、相同方式共享和禁止演绎等条件。例如，禁止演绎许可不授权公开分享译本。作品是否进入公有领域因司法辖区而异；现代译本、编辑新增内容、序言及插图可能独立于古旧原文受到保护。

3. MIT 许可证不为图书内容授予许可。 本项目的 MIT 许可证覆盖软件及随附文档；它不授予输入图书或其他第三方内容的任何权利，也不会自动适用于生成的文件。输出内容的使用仍须遵守适用法律及相关许可或授权。工具不会判定著作权归属，也不会核实您的预期使用方式是否获准。

4. 保留信息不等于核实权利。 生成 EPUB 时，工具会尽量保留源图书的署名与权利元数据。这并不代表翻译或分发已获许可。请检查输出内容，并按适用许可或授权的要求，保留或补充署名、版权声明、许可信息及修改说明。

5. 不提供担保；责任限制。 软件按本项目 MIT 许可证的规定“按原样”提供，不附带任何担保。在适用法律允许的范围内，作者及著作权人按该许可证的规定，不承担因使用软件而产生的责任。

如对项目有问题或建议，请通过 issue 联系我们。

Disclaimer

bilingual_book_maker helps users create multilingual versions of books and other documents.

1. Use only material you are entitled to translate. This includes works for which you hold the necessary rights, works whose license or the rights holder's permission allows your intended use, works in the public domain under applicable law, and uses otherwise permitted by applicable law. Owning or buying a copy does not itself grant translation rights.

2. Check translation and distribution rights separately. Translation is generally an adaptation (a derivative work). Personal use is not automatically exempt from copyright restrictions. If you share a translation, ensure that your license, permission, or applicable law also allows distribution of everything included in the output, including any original text and images. The same license or permission may cover both translation and distribution. For Creative Commons works, check the specific license and version, including attribution, NonCommercial, ShareAlike, and NoDerivatives conditions where applicable. For example, NoDerivatives licenses do not authorize public sharing of translations. Public-domain status varies by jurisdiction; modern translations, editorial contributions, forewords, and illustrations may be protected separately from an older original.

3. The MIT license does not license book content. The project's MIT license covers its software and associated documentation; it grants no rights to input books or other third-party content and does not automatically apply to generated files. Use of the output remains subject to applicable law and any relevant licenses or permissions. The tool does not determine copyright ownership or verify that your intended use is permitted.

4. Preservation is not rights verification. For EPUB output, the tool carries over source attribution and rights metadata where it can. This does not establish that translation or distribution is permitted. Check the output and retain or supply attribution, copyright notices, license information, and indications of changes as required by the applicable license or permission.

5. No warranty; limitation of liability. The software is provided “as is,” without warranty, as set out in the project's MIT license. To the extent permitted by applicable law, the authors and copyright holders disclaim liability arising from use of the software, as set out in that license.

For questions or suggestions about the project, please open an issue.

Zh Docker (`docs/zh/docker.md`) Copy Section

Docker

如果不想自己配置 Python，就用 Docker。每次合并到 main 以及每次发布版本标签时，镜像都会发布到 GitHub Container Registry。容器运行的是 python make_book.py，所以本站介绍的每个参数都原样可用。

镜像与标签 Copy Chapter

镜像有三个，由同一个 Dockerfile 构建。

docker pull ghcr.io/yihong0618/bilingual_book_maker:latest

挂载 Copy Chapter

• **把你的书所在文件夹挂载到 /book。**以 /book/<file> 的形式传入书名。译好的书会写回同一个文件夹。
• 把一个命名卷挂载到 /root/.cache（pdf 和 pdf-cuda 镜像）。docling 的模型在第一次 --to-epub 运行时下载到这里，约 500 MB。没有这个卷的话，每次运行都会重新下载。

容器以 root 身份运行，所以往挂载的文件夹里写入总是可以的。在 Linux 上，它写出的文件归 root 所有：事后 chown 一下，或者加上 --user $(id -u)。

key 请用环境变量传入，而不要写在命令行上：-e OPENAI_API_KEY。

按系统翻译 EPUB Copy Chapter

=== "Linux / macOS"

```bash
docker run --rm \
  -v "$PWD":/book \
  -e OPENAI_API_KEY \
  ghcr.io/yihong0618/bilingual_book_maker:latest \
  --book_name /book/my_book.epub \
  --language zh-hans \
  --use_context session
```

=== "Windows PowerShell"

```powershell
docker run --rm `
  -v "${PWD}:/book" `
  -e OPENAI_API_KEY `
  ghcr.io/yihong0618/bilingual_book_maker:latest `
  --book_name /book/my_book.epub `
  --language zh-hans `
  --use_context session
```

一个完全不需要 key 的测试，走免费的 Google 路线：

docker run --rm \
  -v "$PWD":/book \
  ghcr.io/yihong0618/bilingual_book_maker:latest \
  --book_name /book/animal_farm.epub \
  --api_format google \
  --test \
  --test_num 1 \
  --language zh-hant

按系统翻译 PDF Copy Chapter

latest 镜像里没有 Pandoc，也没有 PDF 相关的包，所以不能运行 --to-epub。有 NVIDIA 显卡请使用 pdf-cuda 标签，其他情况都用 pdf。

=== "带 NVIDIA 显卡的 Linux"