Bilingual Book Maker

https://github.com/yihong0618/bilingual_book_maker
Admin
Bilingual Book Maker is an AI translation tool that uses ChatGPT to assist users in creating...
Tokens:193,969
Snippets:1,355
Trust Score:9.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Clone repository and install dependencies

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translate-with-an-agent

Required setup: clone the repository and install dependencies. Use `pip install ".[pdf]"` if you have PDFs.

```bash
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
```

--------------------------------

### Install PDF extra with uv

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Installs the PDF extra using uv.

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

--------------------------------

### Install PDF extra with uv for CPU build

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Installs the PDF extra with uv, specifying the CPU backend.

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

--------------------------------

### More understandable example with python3 or python

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Home

A basic example using an API base URL and context session. Includes a variant for when python3 is not in your PATH.

```shell
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
```

--------------------------------

### Example commands using --prompt

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Prompt-files

Three example invocations of make_book.py with different prompt sources: a sample text file, a JSON file, and an inline prompt string.

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

--------------------------------

### Install dependencies from requirements.txt

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Python

Installs the pinned, tested dependencies from requirements.txt. Alternatively, pip install . works and takes whatever versions resolve today.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install from PyPI with pip install -U bbook_maker

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Python

Installs the published package from PyPI, providing the bbook_maker command. Requires Python 3.10 or newer. The published package does not include the PDF-to-EPUB route.

```bash
pip install -U bbook_maker
```

--------------------------------

### Check install with bbook_maker --help

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Python

Displays help for the bbook_maker command, which is the authority on every flag.

```bash
bbook_maker --help
```

--------------------------------

### Install PDF extra from repository clone

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Installs the PDF extra from a clone of the repository. Required for --to-epub functionality.

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

--------------------------------

### Install bbm-plan skill for Claude Code and other agents

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translate-with-an-agent

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

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

--------------------------------

### Check install from checkout with python make_book.py --help

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Python

Displays help for the make_book.py command when running from a checkout. Uses the same flags as bbook_maker.

```bash
python make_book.py --help
```

--------------------------------

### Various translation commands using make_book.py

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/README.md

The block contains a series of example commands for using make_book.py with different translation backends and options, including OpenAI, Gemini, DeepL, Claude, custom APIs, and providers. It includes commands for quick tests, full-book translation, parallel workers, model rotation, prompt customization, and translating specific tags. The commands assume OpenAI-compatible API access unless an --api_format or --provider flag is specified. There is also an environment variable export for the OpenAI API key, and a note that if using pip install, the command 'python3 make_book.py' can be replaced with 'bbook_maker' with the same arguments.

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

```shell
python3 make_book.py --book_name test_books/Lex_Fridman_episode_322.srt --key ${openai_key} --test
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --language zh-hans --use_context session
```

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

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --parallel-workers 4
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --key ${openai_key} --model_list gpt-5-mini,gpt-4o-mini
```

```shell
export OPENAI_API_KEY=${your_api_key}
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --model gpt-4o --use_context --language ja
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --api_base "https://api.lingyiwanwu.com/v1" --key ${key} --model yi-34b-chat-0205 --use_context session
```

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

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

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --api_format customapi --api_base ${custom_api} --language ja
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --provider siliconflow --language ja --use_context session
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --translate-tags div,p
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --plan-dry-run
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --plan-classify all
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template_sample.txt
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --prompt prompt_template.json
```

```shell
python3 make_book.py --book_name test_books/animal_farm.epub --prompt "Please translate \`{text}\` to {language}"
```

```shell
python3 make_book.py --book_name test_books/the_little_prince.txt --test --language zh-hans
```

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

```shell
python3 make_book.py --api_format caiyun --key 3975l6lr5pcbvidl6jl2 --book_name test_books/animal_farm.epub
```

```shell
export BBM_CAIYUN_API_KEY=${your_api_key}
```

--------------------------------

### pip install with pdf extra (not yet available)

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

This command attempts to install the 'pdf' extra, but it does not install the route and does not fail. pip treats the unknown extra as a warning, installs the last release without docling, and exits 0.

```text
pip install "bbook_maker[pdf]"
```

--------------------------------

### Install tesseract on Debian and Ubuntu

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/docs/en/features/pdf-ocr-engines.md

Install the tesseract program and its language files on Debian and Ubuntu.

```bash
apt install tesseract-ocr tesseract-ocr-chi-sim
```

--------------------------------

### Install dependencies

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Home

Install required Python packages using pip. Use either the requirements.txt file or the bbook_maker package.

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

--------------------------------

### Configure provider and run translation with provider JSON

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Home

Copy the example provider configuration and edit it, then run the translation command with the --provider flag and --test mode.

```shell
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
```

--------------------------------

### Install and run bbook_maker with OpenAI API key

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/docs/en/index.md

Installs the bbook_maker package, sets the OpenAI API key, and runs the tool on an EPUB file with session context. The command writes a bilingual EPUB file next to the original. The default model is gpt-6-luna and the default target language is Simplified Chinese.

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

--------------------------------

### Translate with gpt-6-luna and classify with Jev

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Provider-file-and-extra-models

Command-line example showing how to run bbook_maker with a translation model and Jev as the classifier. Requires JEV_API_KEY or TYPESAFE_API_KEY in the environment.

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

--------------------------------

### Test run with --test flag

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Reads two pages first to verify the setup. The --test flag translates only a few blocks.

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

--------------------------------

### Provider JSON file example

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Provider-file-and-extra-models

Example of a provider entry in the provider JSON file. It defines a provider named 'siliconflow' with an OpenAI-compatible API style, base URL, default models, and environment variable for the API key.

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

--------------------------------

### Configure provider and test translation

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/README.md

Setup provider configuration and run a translation test. Ensure you edit bbm_providers.json before running the make_book command.

```shell
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

```

--------------------------------

### Invoke bbm-plan skill in Codex

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translate-with-an-agent

Start codex in the checkout and describe the job or name the skill. Example: translate an EPUB to Japanese.

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

--------------------------------

### Codex route with api_format codex

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translating-with-an-LLM

Codex (ChatGPT plan) example: uses the Codex CLI, which must be installed and signed in (codex login). It runs gpt-6-luna by default; add --model <id> for another. The thread is the context, so no --use_context is needed. It ignores --api_base and --key.

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

--------------------------------

### Build Docker image and run

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Home

Builds the image locally with tag bilingual_book_maker, then runs it with a mounted book folder and basic flags.

```shell
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
```

--------------------------------

### Install tesseract on macOS with Homebrew

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/docs/en/features/pdf-ocr-engines.md

Install the tesseract program and its language files on macOS using Homebrew.

```bash
brew install tesseract
```

--------------------------------

### bbook_maker one-command examples for each LLM vendor

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translating-with-an-LLM

One-line commands for each supported LLM vendor. The key can come from the environment (see Keys). Claude uses a claude-* model id to select the anthropic format; Gemini uses --api_format gemini and --interval paces the free tier; Qwen-MT on DashScope requires a source/target pair; Groq requires --model; LiteLLM uses the model name from its config; OrcaRouter uses --model orcarouter or pins a model with --provider orcarouter --model <id>; Ollama can use --api_base for a non-local host; Azure OpenAI uses the deployment's OpenAI-compatible URL and deployment name as the model; Codex requires codex login first.

```bash
bbook_maker --book_name my_book.epub --model claude-sonnet-4-6 --key ${claude_key} --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_format gemini --key ${gemini_key} --model gemini-flash-latest --use_context
```

```bash
bbook_maker --book_name my_book.epub --api_format qwen --key ${qwen_key} --model qwen-mt-turbo --language "Simplified Chinese"
```

```bash
bbook_maker --book_name my_book.epub --api_format xai --key ${xai_key} --model grok-4.3 --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_format groq --key ${groq_key} --model llama-3.3-70b-versatile --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_format litellm --model ${name_in_your_litellm_config} --use_context session
```

```bash
bbook_maker --book_name my_book.epub --model orcarouter --key ${orcarouter_key} --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_base http://localhost:11434/v1 --model ${ollama_model_name} --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_base "https://api.lingyiwanwu.com/v1" --key ${key} --model yi-34b-chat-0205 --use_context session
```

```bash
bbook_maker --book_name my_book.epub --api_base 'https://example-endpoint.openai.azure.com/openai/v1' --key ${azure_key} --model 'deployment-name' --use_context session
```

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

--------------------------------

### Run with a local model via --api_base

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translating-with-an-LLM

Run the tool against a local OpenAI-compatible endpoint (Ollama, llama.cpp, LM Studio). No API key is needed; point --api_base at the local server and choose a model. The example uses qwen3:8b and session context.

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

--------------------------------

### Retranslate start_str tag only (empty end_str)

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Command-line-options

Re-translates only the starting tag by providing an empty end_str. Requires all four arguments; the empty end_str means only the start tag is used. Deletes from the start tag to the next tag and re-translates.

```sh
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' ''
```

--------------------------------

### Show help and run with Google translation

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Model-and-language-notes

Two commands: first shows help for bbook_maker, second runs it with the Google translation service and Japanese as the target language. The translation services take no model and ignore model settings.

```sh
bbook_maker --help
```

```sh
bbook_maker --book_name book.epub --api_format google --language ja
```

--------------------------------

### Install easyocr via pip

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/docs/en/features/pdf-ocr-engines.md

Install the easyocr engine with pip. Its models are downloaded on first use into ~/.EasyOCR/model.

```bash
pip install easyocr
```

--------------------------------

### Command-line flags for local translation with hosted image and classification models

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Provider-file-and-extra-models

Equivalent to the provider file example, using command-line flags. The local server requires no key, so the run's key is empty; the classifier's key must be provided via --classify-key.

```bash
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
```

--------------------------------

### Run bbook_maker with a prompt file

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Translating-with-an-LLM

Run the translator with a prompt file and session context. The prompt file must contain a user template with {text}; other placeholders are refused at startup.

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

--------------------------------

### Install PDF extra on Linux CPU only

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Installs the PDF extra on Linux for CPU-only usage, using the CPU index to avoid downloading CUDA packages.

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

--------------------------------

### Run make_book.py on CPU-only

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Recommended-settings-for-PDF

Run the book maker with a PDF input, explicitly using the CPU device. Extraction is slower than on a GPU (e.g., 26.3 s vs 10.6 s for a two-page OCR scan).

```bash
python make_book.py \
  --book_name paper.pdf \
  --to-epub \
  --device cpu \
  --use_context session
```

--------------------------------

### Install PDF extra on Windows with NVIDIA

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Installs the PDF extra on Windows with NVIDIA GPU, using the cu126 index because PyPI's Windows wheel is CPU-only.

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

--------------------------------

### PDF to bilingual EPUB: install and convert commands

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Home

Install the PDF extra, test on two pages first, then convert the whole file. Requires Pandoc 3.1.12 or newer.

```shell
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
```

--------------------------------

### pip warning for missing pdf extra

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Installing-the-PDF-extra

Output shown when running the pip install command with the 'pdf' extra. It warns that the extra is not provided and installs the last release without docling.

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

--------------------------------

### Run bbook_maker with Groq OpenAI-compatible endpoint

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Model-and-language-notes

Use --api_base to point to an OpenAI-compatible endpoint, here Groq. The --key flag supplies the API key, and --model selects the model. This route supports structured output, --use_context, parallel workers, async, and the Batch API as the endpoint supports them.

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

--------------------------------

### Retranslate from start_str to end_str

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Command-line-options

Re-translates a portion of an EPUB file from a start string to an end string. Requires all four arguments: translated filepath, file name in EPUB, start string, and end string. Deletes the content between the tags and re-translates it.

```sh
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 start_str tag with auto filename lookup

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Command-line-options

Re-translates only the starting tag while automatically finding the filename by providing empty file_name_in_epub and end_str. Requires all four arguments; empty file_name_in_epub enables automatic filename lookup. Deletes from the start tag to the next tag and re-translates.

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

--------------------------------

### bbook_maker command with --api_base, --key, --model, --language

Source: https://github.com/yihong0618/bilingual_book_maker/wiki/Model-and-language-notes

Example command showing how to specify an endpoint, API key, model, and target language. The --model flag accepts any model id served by the endpoint; there is no built-in model list.

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

--------------------------------

### Define custom API provider in bbm_providers.json and run make_book.py

Source: https://github.com/yihong0618/bilingual_book_maker/blob/main/README.md

Configure a custom API provider in a JSON config file, then run the tool with the provider either by passing an API key directly or by setting the environment variable defined in the config. The JSON defines provider settings such as api_style, base_url, default_models, env_key, and optional prices for cost tracking. The provider config file can be project-level ./bbm_providers.json or global ~/.bbm/providers.json, with project-level taking priority.

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

```shell
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
```
Tokens:
Raw