https://github.com/oomol-lab/epub-translator
Use LLM to losslessly translate EPUB e-books, retain the original layout, and generate bilingual comparisons.
https://github.com/oomol-lab/epub-translator
ai epub oomol translation
Last synced: about 2 months ago
JSON representation
Use LLM to losslessly translate EPUB e-books, retain the original layout, and generate bilingual comparisons.
- Host: GitHub
- URL: https://github.com/oomol-lab/epub-translator
- Owner: oomol-lab
- License: mit
- Created: 2025-07-01T08:55:07.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-08-04T06:31:14.000Z (2 months ago)
- Last Synced: 2025-08-10T03:31:16.350Z (about 2 months ago)
- Topics: ai, epub, oomol, translation
- Language: Python
- Homepage: https://hub.oomol.com/package/books-translator
- Size: 6.3 MB
- Stars: 399
- Watchers: 3
- Forks: 18
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## 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'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'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/).
