<div align=center>
<h1>EPUB Translator</h1>
<p>
<a href="https://github.com/oomol-lab/epub-translator/actions/workflows/build.yml" target="_blank"><img src="https://img.shields.io/github/actions/workflow/status/oomol-lab/epub-translator/build.yml" alt"ci" /></a>
<a href="https://pypi.org/project/epub-translator/" target="_blank"><img src="https://img.shields.io/badge/pip_install-epub--translator-blue" alt="pip install epub-translator" /></a>
<a href="https://pypi.org/project/epub-translator/" target="_blank"><img src="https://img.shields.io/pypi/v/epub-translator.svg" alt"pypi epub-translator" /></a>
<a href="https://pypi.org/project/epub-translator/" target="_blank"><img src="https://img.shields.io/pypi/pyversions/epub-translator.svg" alt="python versions" /></a>
<a href="https://github.com/oomol-lab/epub-translator/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/github/license/oomol-lab/epub-translator" alt"license" /></a>
</p>
<p><a href="https://hub.oomol.com/package/books-translator?open=true" target="_blank"><img src="https://static.oomol.com/assets/button.svg" alt="Open in OOMOL Studio" /></a></p>
<p>English | <a href="./README_zh-CN.md">中文</a></p>
</div>
## Introduction
epub-translator uses AI big models to automatically translate EPUB e-books, and retains 100% of the original book's format, illustrations, catalog and layout, while generating bilingual comparison versions for easy language learning or international sharing.
Whether you are a developer, language learner, or e-book lover, epub-translator can help you easily overcome language barriers.
- [x] **Multi-language translation**: Supports translation between mainstream languages such as English, Chinese, Japanese, Spanish, French, and German.
- [x] **Bilingual comparison**: Generates bilingual EPUBs with top-down comparisons for easy comparison and learning.
- [x] **Insert prompt words**: Guide AI translation, such as glossary, character name list, etc.
- [x] **Optional AI model**: Supports mainstream big models such as DeepSeek and ChatGPT.
- [x] **High-performance parallelism**: AI requests multiple concurrent channels to quickly translate the entire book.
## Environment
You can call EPUB Translator directly as a library, or use [OOMOL Studio](https://oomol.com/) to run it directly.
### Run with OOMOL Studio
OOMOL uses container technology to directly package the dependencies required by EPUB Translator, and it is ready to use out of the box.
[](https://www.youtube.com/watch?v=QsAdiskxfXI)
### Call directly as a library
You can also write python code directly and call it as a library. At this time, you need python 3.10 or higher (3.10.16 is recommended).
```shell
pip install epub-translator
```
## Quick start
First, construct the `LLM` object that calls the AI Large Language Model.
```python
from epub_translator import LLM
llm = LLM(
key="<LLM-API-KEY>", # LLM's API key
url="https://api.deepseek.com", # LLM's base URL
model="deepseek-chat", # LLM's model name
token_encoding="o200k_base", # Local model for calculating the number of tokens
)
```
Then, you can call the `translate` method to translate.
```python
from epub_translator import translate, Language
translate(
llm=llm, # llm object constructed in the previous step
source_path="/path/to/epub/file", # Original EPUB file to be translated
translated_path="/path/to/translated/epub/file", # Path to save the translated EPUB
target_language=Language.ENGLISH, # Target language for translation, in this case English.
)
```
After calling this method, the translation can be inserted under the original text while retaining the EPUB format.
## Function
### Save translation progress
Calling `translate` to translate the entire EPUB e-book takes a long time, and this process may be interrupted for various reasons. For example, when calling LLM, an error is reported and the process is interrupted due to network reasons, or the user can't wait and manually interrupts the process.
EPUB Translator can cache the translated content as a local file, so that when translating the same book, the translation progress can be saved and the progress can be restored from the last translation interruption.
Just configure the `working_path` field when calling `translate` and specify a path to cache the files generated by the translation. The next time it is started, EPUB Translator will try to read the translation progress from this path in advance.
```python
translate(
..., # other parameters
working_path="/path/to/cache/translating/files",
)
```
Please note that each call to the `translate` method will write a cache file to the folder where the `workspace_path` is located. This will cause the folder to grow larger and larger. You need to handle it yourself, for example, automatically clear the folder after the translation is successful.
### Monitor translation progress
When calling `translate`, pass a callback function through `report_progress`, and receive a `float` type parameter representing the progress from 0.0 to 1.0, so that the translation progress of the whole book can be monitored.
```python
from tqdm import tqdm
from epub_translator import translate
with tqdm(total=1.0, desc="Translating") as bar:
def refresh_progress(progress: float) -> None:
bar.n = progress
bar.refresh()
translate(
..., # other parameters
report_progress=refresh_progress,
)
```
### Insert prompt words
Insert prompt words to guide the AI language model on how to translate. For example, you can insert a glossary so that AI can unify the terms when translating. Just add the `user_prompt` field when calling `translate`.
```python
translate(
..., # other parameters
user_prompt='Le Petit Prince should be translated as "Little Prince".',
)
```
### Large Language Model Parameters
There are more configuration options when building the `LLM` object.
```python
llm = LLM(
key="<LLM-API-KEY>", # LLM's API key
url="https://api.deepseek.com", # LLM's base URL
model="deepseek-chat", # LLM's model name
token_encoding="o200k_base", # Local model for calculating the number of tokens
timeout=60.0, # Request timeout (in seconds)
top_p=0.6, # Creativity
temperature=0.85, # Temperature
retry_times=5, # Retry times. If the request still fails after this number, an error will be reported
retry_interval_seconds=6.0, # Retry interval (in seconds)
)
```
## Related open source libraries
[PDF Craft](https://github.com/oomol-lab/pdf-craft) can convert PDF files into various other formats. This project will focus on the processing of PDF files of scanned books. Use this library with the scanned PDF books to convert and translate them. For more information, please refer to [Video: Convert scanned PDF books to EPUB format and translate them into bilingual books](https://www.bilibili.com/video/BV1tMQZY5EYY/).
Raw data
{
"_id": null,
"home_page": "https://hub.oomol.com/package/book-translator",
"name": "epub-translator",
"maintainer": "Tao Zeyu",
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": "i@taozeyu.com",
"keywords": "epub, llm, translation, translator",
"author": "Tao Zeyu",
"author_email": "i@taozeyu.com",
"download_url": "https://files.pythonhosted.org/packages/e5/c9/c1913014251aa253c74348ba589df446f91fa0a7736912a290840d3f068b/epub_translator-0.0.6.tar.gz",
"platform": null,
"description": "<div align=center>\n <h1>EPUB Translator</h1>\n <p>\n <a href=\"https://github.com/oomol-lab/epub-translator/actions/workflows/build.yml\" target=\"_blank\"><img src=\"https://img.shields.io/github/actions/workflow/status/oomol-lab/epub-translator/build.yml\" alt\"ci\" /></a>\n <a href=\"https://pypi.org/project/epub-translator/\" target=\"_blank\"><img src=\"https://img.shields.io/badge/pip_install-epub--translator-blue\" alt=\"pip install epub-translator\" /></a>\n <a href=\"https://pypi.org/project/epub-translator/\" target=\"_blank\"><img src=\"https://img.shields.io/pypi/v/epub-translator.svg\" alt\"pypi epub-translator\" /></a>\n <a href=\"https://pypi.org/project/epub-translator/\" target=\"_blank\"><img src=\"https://img.shields.io/pypi/pyversions/epub-translator.svg\" alt=\"python versions\" /></a>\n <a href=\"https://github.com/oomol-lab/epub-translator/blob/main/LICENSE\" target=\"_blank\"><img src=\"https://img.shields.io/github/license/oomol-lab/epub-translator\" alt\"license\" /></a>\n </p>\n <p><a href=\"https://hub.oomol.com/package/books-translator?open=true\" target=\"_blank\"><img src=\"https://static.oomol.com/assets/button.svg\" alt=\"Open in OOMOL Studio\" /></a></p>\n <p>English | <a href=\"./README_zh-CN.md\">\u4e2d\u6587</a></p>\n</div>\n\n## Introduction\n\nepub-translator uses AI big models to automatically translate EPUB e-books, and retains 100% of the original book's format, illustrations, catalog and layout, while generating bilingual comparison versions for easy language learning or international sharing.\n\nWhether you are a developer, language learner, or e-book lover, epub-translator can help you easily overcome language barriers.\n\n- [x] **Multi-language translation**: Supports translation between mainstream languages \u200b\u200bsuch as English, Chinese, Japanese, Spanish, French, and German.\n- [x] **Bilingual comparison**: Generates bilingual EPUBs with top-down comparisons for easy comparison and learning.\n- [x] **Insert prompt words**: Guide AI translation, such as glossary, character name list, etc.\n- [x] **Optional AI model**: Supports mainstream big models such as DeepSeek and ChatGPT.\n- [x] **High-performance parallelism**: AI requests multiple concurrent channels to quickly translate the entire book.\n\n## Environment\n\nYou can call EPUB Translator directly as a library, or use [OOMOL Studio](https://oomol.com/) to run it directly.\n\n### Run with OOMOL Studio\n\nOOMOL uses container technology to directly package the dependencies required by EPUB Translator, and it is ready to use out of the box.\n\n[](https://www.youtube.com/watch?v=QsAdiskxfXI)\n\n### Call directly as a library\n\nYou can also write python code directly and call it as a library. At this time, you need python 3.10 or higher (3.10.16 is recommended).\n\n```shell\npip install epub-translator\n```\n\n## Quick start\n\nFirst, construct the `LLM` object that calls the AI \u200b\u200bLarge Language Model.\n\n```python\nfrom epub_translator import LLM\n\nllm = LLM(\n key=\"<LLM-API-KEY>\", # LLM's API key\n url=\"https://api.deepseek.com\", # LLM's base URL\n model=\"deepseek-chat\", # LLM's model name\n token_encoding=\"o200k_base\", # Local model for calculating the number of tokens\n)\n```\n\nThen, you can call the `translate` method to translate.\n\n```python\nfrom epub_translator import translate, Language\n\ntranslate(\n llm=llm, # llm object constructed in the previous step\n source_path=\"/path/to/epub/file\", # Original EPUB file to be translated\n translated_path=\"/path/to/translated/epub/file\", # Path to save the translated EPUB\n target_language=Language.ENGLISH, # Target language for translation, in this case English.\n)\n```\n\nAfter calling this method, the translation can be inserted under the original text while retaining the EPUB format.\n\n\n\n## Function\n\n### Save translation progress\n\nCalling `translate` to translate the entire EPUB e-book takes a long time, and this process may be interrupted for various reasons. For example, when calling LLM, an error is reported and the process is interrupted due to network reasons, or the user can't wait and manually interrupts the process.\n\nEPUB Translator can cache the translated content as a local file, so that when translating the same book, the translation progress can be saved and the progress can be restored from the last translation interruption.\n\nJust configure the `working_path` field when calling `translate` and specify a path to cache the files generated by the translation. The next time it is started, EPUB Translator will try to read the translation progress from this path in advance.\n\n```python\ntranslate(\n ..., # other parameters\n working_path=\"/path/to/cache/translating/files\",\n)\n```\n\nPlease note that each call to the `translate` method will write a cache file to the folder where the `workspace_path` is located. This will cause the folder to grow larger and larger. You need to handle it yourself, for example, automatically clear the folder after the translation is successful.\n\n### Monitor translation progress\n\nWhen calling `translate`, pass a callback function through `report_progress`, and receive a `float` type parameter representing the progress from 0.0 to 1.0, so that the translation progress of the whole book can be monitored.\n\n```python\nfrom tqdm import tqdm\nfrom epub_translator import translate\n\nwith tqdm(total=1.0, desc=\"Translating\") as bar:\n def refresh_progress(progress: float) -> None:\n bar.n = progress\n bar.refresh()\n\n translate(\n ..., # other parameters\n report_progress=refresh_progress,\n )\n```\n\n### Insert prompt words\n\nInsert prompt words to guide the AI \u200b\u200blanguage model on how to translate. For example, you can insert a glossary so that AI can unify the terms when translating. Just add the `user_prompt` field when calling `translate`.\n\n```python\ntranslate(\n ..., # other parameters\n user_prompt='Le Petit Prince should be translated as \"Little Prince\".',\n)\n```\n\n### Large Language Model Parameters\n\nThere are more configuration options when building the `LLM` object.\n\n```python\nllm = LLM(\n key=\"<LLM-API-KEY>\", # LLM's API key\n url=\"https://api.deepseek.com\", # LLM's base URL\n model=\"deepseek-chat\", # LLM's model name\n token_encoding=\"o200k_base\", # Local model for calculating the number of tokens\n timeout=60.0, # Request timeout (in seconds)\n top_p=0.6, # Creativity\n temperature=0.85, # Temperature\n retry_times=5, # Retry times. If the request still fails after this number, an error will be reported\n retry_interval_seconds=6.0, # Retry interval (in seconds)\n)\n```\n\n## Related open source libraries\n\n[PDF Craft](https://github.com/oomol-lab/pdf-craft) can convert PDF files into various other formats. This project will focus on the processing of PDF files of scanned books. Use this library with the scanned PDF books to convert and translate them. For more information, please refer to [Video: Convert scanned PDF books to EPUB format and translate them into bilingual books](https://www.bilibili.com/video/BV1tMQZY5EYY/).",
"bugtrack_url": null,
"license": "MIT",
"summary": "Translate the epub book using LLM. The translated book will retain the original text and list the translated text side by side with the original text.",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://hub.oomol.com/package/book-translator",
"Repository": "https://github.com/oomol-flows/books-translator"
},
"split_keywords": [
"epub",
" llm",
" translation",
" translator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0a12cd5267267b6b58498a0bed55b39f821186995d02320ba7b61034a52d0de8",
"md5": "d116ebd16c39cfed109e2b925444411f",
"sha256": "a630dec90c3e0e42c0204618de64a15995073d1f9b99a8a8503928e11271cae3"
},
"downloads": -1,
"filename": "epub_translator-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d116ebd16c39cfed109e2b925444411f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 33882,
"upload_time": "2025-07-22T04:18:21",
"upload_time_iso_8601": "2025-07-22T04:18:21.152233Z",
"url": "https://files.pythonhosted.org/packages/0a/12/cd5267267b6b58498a0bed55b39f821186995d02320ba7b61034a52d0de8/epub_translator-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5c9c1913014251aa253c74348ba589df446f91fa0a7736912a290840d3f068b",
"md5": "7aff3c9f8c0b3ecfc8cae1453855f6d2",
"sha256": "82af4f6c37572c08756ee54552e17129c499510951dcc1e3d44cc744ddc37d15"
},
"downloads": -1,
"filename": "epub_translator-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "7aff3c9f8c0b3ecfc8cae1453855f6d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 26521,
"upload_time": "2025-07-22T04:18:23",
"upload_time_iso_8601": "2025-07-22T04:18:23.118588Z",
"url": "https://files.pythonhosted.org/packages/e5/c9/c1913014251aa253c74348ba589df446f91fa0a7736912a290840d3f068b/epub_translator-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 04:18:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oomol-flows",
"github_project": "books-translator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "epub-translator"
}
JSON
