Use --translate-tags to specify tags that need translation. Use comma to separate multiple tags. For example: --translate-tags h1,h2,h3,p,div

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

• --book_from: Use --book_from option to specify e-reader type (Now only kobo is available), and use --device_path to specify the mounting point.

• --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. Note that it’s best to look for e-books that are more standardized if possible.

• --prompt: To tweak the prompt, use the --prompt parameter. Valid placeholders for the user role template include {text} and {language}. 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 (example of a text file can be found at ./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_sample.json (example of a JSON file can be found at ./prompt_template_sample.json).
  • You can now use PromptDown (https://github.com/btfranklin/promptdown) format (.md files) for more structured prompts: --prompt prompt_md.prompt.md. PromptDown supports both traditional system messages and developer messages (used by newer AI models). Example: ``markdown # Translation Prompt

Developer Message

You are a professional translator who specializes in accurate translations.

Conversation

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

• --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. gpt3.5 limits the total_token to 4090. 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 reaching the limit. You have to choose your own value, there is no way to know if the limit is reached before sending

• --use_context: prompts the model to create a three-paragraph summary. If it’s the beginning of the translation, it will summarize the entire passage sent (the size depending on --accumulated_num). For subsequent passages, it will amend the summary to include details from the most recent passage, creating a running one-paragraph context payload of the important details of the entire translated work. This improves consistency of flow and tone throughout the translation. This option is available for all ChatGPT-compatible models and Gemini models.

• --context_paragraph_limit: Use --context_paragraph_limit to set a limit on the number of context paragraphs when using the --use_context option.

• --parallel-workers: Use --parallel-workers to enable parallel EPUB chapter processing. Values greater than 1 spin up multiple workers (recommended: 2-4) and automatically fall back to sequential mode for single-chapter books.

• --temperature: Use --temperature to set the temperature parameter for chatgptapi/gpt4/claude models. 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.

• --translation_style: example: --translation_style "color: #808080; font-style: italic;"

• --retranslate "$translated_filepath" "file_name_in_epub" "start_str" "end_str"(optional): Retranslate from start_str to end_str’s tag: shell 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'

  Retranslate start_str’s tag: shell 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'

• --extra_body: Pass additional JSON parameters to the API. This is useful for models that support extra configuration options. Provide a JSON string with the desired parameters. shell python3 make_book.py --book_name test_books/animal_farm.epub --openai_key ${openai_key} --extra_body '{"chat_template_kwargs": {"enable_thinking": false}}'

• --provider: Use a custom provider defined in bbm_providers.json. Mutually exclusive with --model. See the “Custom API Provider” section above.

• --api_key: API key for custom providers (used with --provider). Can also be set via the env_key field in the provider config.

Examples

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

``shell

Test quickly

python3 make_book.py –book_name test_books/animal_farm.epub –openai_key ${openai_key} –test –language zh-hans

Test quickly for src

python3 make_book.py –book_name test_books/Lex_Fridman_episode_322.srt –openai_key ${openai_key} –test

Or translate the whole book

python3 make_book.py –book_name test_books/animal_farm.epub –openai_key ${openai_key} –language zh-hans

Or translate the whole book using Gemini flash

python3 make_book.py –book_name test_books/animal_farm.epub –gemini_key ${gemini_key} –model gemini

Translate an EPUB with parallel chapter processing

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

Use a specific list of Gemini model aliases

python3 make_book.py –book_name test_books/animal_farm.epub –gemini_key ${gemini_key} –model gemini –model_list gemini-2.5-flash,gemini-2.0-flash

Set env OPENAI_API_KEY to ignore option –openai_key

export OPENAI_API_KEY=${your_api_key}

Use the GPT-4 model with context to Japanese

python3 make_book.py –book_name test_books/animal_farm.epub –model gpt4 –use_context –language ja

Use a specific OpenAI model alias

python3 make_book.py –book_name test_books/animal_farm.epub –model openai –model_list gpt-4-1106-preview –openai_key ${openai_key}

Note you can use other openai like model in this way python3 make_book.py –book_name test_books/animal_farm.epub –model openai –model_list yi-34b-chat-0205 –openai_key ${openai_key} –api_base “https://api.lingyiwanwu.com/v1”

Use a specific list of OpenAI model aliases

python3 make_book.py –book_name test_books/animal_farm.epub –model openai –model_list gpt-4-1106-preview,gpt-4-0125-preview,gpt-3.5-turbo-0125 –openai_key ${openai_key}

Use the DeepL model with Japanese

python3 make_book.py –book_name test_books/animal_farm.epub –model deepl –deepl_key ${deepl_key} –language ja

Use the Claude model with Japanese

python3 make_book.py –book_name test_books/animal_farm.epub –model claude –claude_key ${claude_key} –language ja

Use the CustomAPI model with Japanese

python3 make_book.py –book_name test_books/animal_farm.epub –model customapi –custom_api ${custom_api} –language ja

Use a custom provider (e.g. DeepSeek)

python3 make_book.py –book_name test_books/animal_farm.epub –provider deepseek –api_key sk-xxx –language ja

Translate contents in

and

tags

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

Tweaking the prompt

python3 make_book.py –book_name test_books/animal_farm.epub –prompt prompt_template_sample.txt

or

python3 make_book.py –book_name test_books/animal_farm.epub –prompt prompt_template_sample.json

or

python3 make_book.py –book_name test_books/animal_farm.epub –prompt “Please translate `{text}` to {language}”

Translate books download from Rakuten Kobo on kobo e-reader

python3 make_book.py –book_from kobo –device_path /tmp/kobo

translate txt file

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

aggregated translation txt file

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

Using Caiyun model to translate

(the api currently only support: simplified chinese <-> english, simplified chinese <-> japanese)

the official Caiyun has provided a test token (3975l6lr5pcbvidl6jl2)

you can apply your own token by following this tutorial(https://bobtranslate.com/service/translate/caiyun.html)

python3 make_book.py –model caiyun –caiyun_key 3975l6lr5pcbvidl6jl2 –book_name test_books/animal_farm.epub

Set env BBM_CAIYUN_API_KEY to ignore option –openai_key

export BBM_CAIYUN_API_KEY=${your_api_key} ``

More understandable example

``shell python3 make_book.py –book_name ‘animal_farm.epub’ –openai_key sk-XXXXX –api_base ‘https://xxxxx/v1’

Or python3 is not in your PATH

python make_book.py –book_name ‘animal_farm.epub’ –openai_key sk-XXXXX –api_base ‘https://xxxxx/v1’ ``

Microsoft Azure Endpoints

``shell python3 make_book.py –book_name ‘animal_farm.epub’ –openai_key XXXXX –api_base ‘https://example-endpoint.openai.azure.com’ –deployment_id ‘deployment-name’

Or python3 is not in your PATH

python make_book.py –book_name ‘animal_farm.epub’ –openai_key XXXXX –api_base ‘https://example-endpoint.openai.azure.com’ –deployment_id ‘deployment-name’ ``

Docker

You can use Docker (https://www.docker.com/) if you don’t want to deal with setting up the environment.

``shell

Build image

docker build –tag bilingual_book_maker .

Run container

“$folder_path” represents the folder where your book file locates. Also, it is where the processed file will be stored.

Windows PowerShell

$folder_path=your_folder_path # $folder_path=“C:\Users\user\mybook" $book_name=your_book_name # $book_name=“animal_farm.epub” $openai_key=your_api_key # $openai_key=“sk-xxx” language=your_language # see utils.py docker run --rm --name bilingual_book_maker --mount type=bind,source=folder_path,target=‘/app/test_books’ bilingual_book_maker –book_name “/app/test_books/$book_name” –openai_key $openai_key –language $language

Linux

export folder_path={your_folder_path} export book_name={your_book_name} export openai_key={your_api_key} export language={your_language} docker run –rm –name bilingual_book_maker –mount type=bind,source={folder_path},target='/app/test_books' bilingual_book_maker --book_name "/app/test_books/{book_name}“ –openai_key {openai_key} --language "{language}“ ``

For example:

``shell

Linux

docker run –rm –name bilingual_book_maker –mount type=bind,source=/home/user/my_books,target=‘/app/test_books’ bilingual_book_maker –book_name /app/test_books/animal_farm.epub –openai_key sk-XXX –test –test_num 1 –language zh-hant ``

Notes

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

Thanks

• @yetone (https://github.com/yetone)

Contribution

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

Others

• better
  • 书译 BookTranslator -> Book Translator (https://www.booktranslator.app)

Appreciation

Thank you, that’s enough. image ²: https://platform.openai.com/account/api-keys ¹: https://github.com/psf/black