想要在不丢失原文语境的情况下阅读外文书籍吗？EPUB翻译器能够借助AI技术，将任意EPUB格式的电子书转换为双语文本对照版本，让译文与原文并排呈现。

无论您是在学习新语言、进行学术研究，还是单纯享受外国文学作品，这款工具都能帮您在一本书中同时获得两种语言版本，且完整保留原书的排版、图片和结构。

在线版本

如果您不想在本地安装EPUB翻译器，可以使用官方推出的在线应用Inkora - EPUB翻译器，它提供了同样的双语文本翻译流程。只需上传一个EPUB文件，即可直接在浏览器中体验主要功能。

安装

pip install epub-translator

要求：Python 3.11、3.12 或 3.13

快速入门

使用OOMOL Studio（推荐）

通过OOMOL Studio的可视化界面使用EPUB翻译器是最简单的方式：

使用Python API

from epub_translator import LLM, translate, language, SubmitKind

# 使用您的API密钥初始化LLM客户端
llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
)

# 使用语言常量翻译EPUB文件
translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
)

带进度跟踪

from tqdm import tqdm

with tqdm(total=100, desc="翻译", unit="%") as pbar:
    last_progress = 0.0

    def on_progress(progress: float):
        nonlocal last_progress
        increment = (progress - last_progress) * 100
        pbar.update(increment)
        last_progress = progress

    translate(
        source_path="source.epub",
        target_path="translated.epub",
        target_language="English",
        submit=SubmitKind.APPEND_BLOCK,
        llm=llm,
        on_progress=on_progress,
    )

API参考

LLM类

初始化用于翻译的LLM客户端：

LLM(
    key: str,                          # API密钥
    url: str,                          # API端点URL
    model: str,                        # 模型名称（例如，“gpt-4”）
    token_encoding: str,               # 令牌编码方式（例如，“o200k_base”）
    cache_path: PathLike | None = None,           # 缓存目录路径
    timeout: float | None = None,                  # 请求超时时间（秒）
    top_p: float | tuple[float, float] | None = None,
    temperature: float | tuple[float, float] | None = None,
    retry_times: int = 5,                         # 失败后重试次数
    retry_interval_seconds: float = 6.0,          # 重试间隔时间（秒）
    log_dir_path: PathLike | None = None,         # 日志目录路径
)

translate函数

翻译EPUB文件：

translate(
    source_path: PathLike | str,       # 源EPUB文件路径
    target_path: PathLike | str,       # 目标EPUB文件路径
    target_language: str,              # 目标语言（例如，“英语”、“中文”）
    submit: SubmitKind,                # 插入译文的方式（REPLACE、APPEND_TEXT或APPEND_BLOCK）
    user_prompt: str | None = None,    # 自定义翻译指令
    max_retries: int = 5,              # 翻译失败后的最大重试次数
    max_group_tokens: int = 2600,      # 每组翻译的最大令牌数
    concurrency: int = 1,              # 并发翻译任务数量（默认为1）
    llm: LLM | None = None,            # 单一LLM实例用于翻译和填充
    translation_llm: LLM | None = None,  # 专门用于翻译的LLM实例（覆盖llm）
    fill_llm: LLM | None = None,       # 专门用于XML填充的LLM实例（覆盖llm）
    on_progress: Callable[[float], None] | None = None,  # 进度回调函数（0.0–1.0）
    on_fill_failed: Callable[[FillFailedEvent], None] | None = None,  # 错误回调函数
)

注意：必须提供llm，或者同时提供translation_llm和fill_llm。使用独立的LLM实例可以根据具体任务需求进行优化。

提交模式

submit参数决定了译文如何插入到文档中。请使用SubmitKind枚举来指定插入方式：

from epub_translator import SubmitKind

# 三种可用模式：
# - SubmitKind.REPLACE：用译文替换原文内容，生成单语种输出
# - SubmitKind.APPEND_TEXT：将译文以内联文本形式追加到原文之后，两种语言出现在同一段落中，保持连续的阅读流
# - SubmitKind.APPEND_BLOCK：将译文以块级元素的形式追加到原文之后，两种语言之间有清晰的视觉分隔，非常适合双语文本对照阅读

模式对比：

• SubmitKind.REPLACE：通过用译文替换原文内容，生成单语种翻译版本。适用于仅需目标语言版本的书籍。

• SubmitKind.APPEND_TEXT：将译文以内联文本形式紧随原文之后插入。两种语言在同一段落中交替出现，形成流畅的阅读体验。

• SubmitKind.APPEND_BLOCK（推荐）：将译文以独立的块级元素（段落）形式插入到原文之后。这种方式能够在视觉上清晰地区分两种语言，特别适合双语文本对照阅读。

示例：

用于双语书籍（推荐）

translate( source_path="source.epub", target_path="translated.epub", target_language=language.ENGLISH, submit=SubmitKind.APPEND_BLOCK, llm=llm, )

用于单语翻译

translate( source_path="source.epub", target_path="translated.epub", target_language=language.ENGLISH, submit=SubmitKind.REPLACE, llm=llm, )

#### 语言常量

EPUB Translator 提供了预定义的语言常量，以方便使用。您可以使用这些常量，而无需将语言名称写成字符串：

```python
from epub_translator import language

# 使用示例：
translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
)

# 您也可以使用自定义的语言字符串：
translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language="Icelandic",  # 对于不在常量中的语言
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
)

使用 on_fill_failed 进行错误处理

通过 on_fill_failed 回调函数监控翻译错误。系统会自动重试失败的翻译，最多尝试 max_retries 次（默认为5次）。大多数错误在重试过程中都会被修复，不会影响最终输出。

from epub_translator import FillFailedEvent

def handle_fill_error(event: FillFailedEvent):
    // 只记录会影响最终 EPUB 文件的关键错误
    if event.over_maximum_retries:
        print(f"关键错误，在 {event.retried_count} 次尝试后：")
        print(f"  {event.error_message}")
        print("  此错误将出现在最终的 EPUB 文件中！")

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
    on_fill_failed=handle_fill_error,
)

理解错误严重性：

FillFailedEvent 包含：

• error_message: str - 错误描述
• retried_count: int - 当前的重试次数（1 到 max_retries）
• over_maximum_retries: bool - 错误是否严重

错误分类：

• 可恢复错误（over_maximum_retries=False）：重试过程中出现的错误。系统会继续重试，通常可以自动解决。大多数情况下可以忽略。

• 严重错误（over_maximum_retries=True）：所有重试尝试都失败后的错误。这些错误会出现在最终的 EPUB 文件中，需要进一步调查。

高级用法：

在调试翻译过程时进行详细日志记录：

def handle_fill_error(event: FillFailedEvent):
    if event.over_maximum_retries:
        // 严重：影响最终输出
        print(f"❌ 严重：{event.error_message}")
    else:
        // 信息性：系统正在重试
        print(f"⚠️  重试 {event.retried_count} 次：{event.error_message}")

双 LLM 架构

使用不同的 LLM 实例分别进行翻译和 XML 结构填充，并设置不同的优化参数：

// 创建两个具有不同温度的 LLM 实例
translation_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
    temperature=0.8,  // 较高的温度用于创意翻译
)

fill_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
    temperature=0.3,  // 较低的温度用于保持结构完整性
)

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    translation_llm=translation_llm,
    fill_llm=fill_llm,
)

配置示例

OpenAI

llm = LLM(
    key="sk-...",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
)

Azure OpenAI

llm = LLM(
    key="your-azure-key",
    url="https://your-resource.openai.azure.com/openai/deployments/your-deployment",
    model="gpt-4",
    token_encoding="o200k_base",
)

其他兼容 OpenAI 的服务

任何具有 OpenAI 兼容 API 的服务都可以使用：

llm = LLM(
    key="your-api-key",
    url="https://your-service.com/v1",
    model="your-model",
    token_encoding="o200k_base",  // 根据您的模型编码进行匹配
)

高级功能

自定义翻译提示

提供特定的翻译指导：

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language="English",
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
    user_prompt="使用正式语言并保留技术术语",
)

缓存以恢复进度

启用缓存功能，以便在发生故障后恢复翻译进度：

llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
    cache_path="./translation_cache",  // 翻译结果将在此处缓存
)

并发翻译

通过同时处理多个文本段来加快翻译速度。使用 concurrency 参数控制同时运行的翻译任务数量：

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language="English",
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
    concurrency=4,  // 同时处理 4 个文本段
)

性能提示：

• 建议从 concurrency=4 开始，根据您的 API 速率限制和系统资源进行调整
• 更高的并发值可以显著缩短大型书籍的翻译时间
• 无论并发设置如何，翻译顺序都会保持不变
• 请密切关注您的 API 提供商的速率限制，以免被限流

线程安全：

当使用 concurrency > 1 时，请确保任何自定义回调函数（on_progress、on_fill_failed）都是线程安全的。内置回调函数默认是线程安全的。

令牌使用监控

在翻译过程中跟踪令牌消耗情况，以便监控 API 成本和使用情况：

from epub_translator import LLM、translate、language 和 SubmitKind

llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
)

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    llm=llm,
)

# 翻译后的访问令牌统计信息
print(f"总令牌数: {llm.total_tokens}")
print(f"输入令牌数: {llm.input_tokens}")
print(f"输入缓存令牌数: {llm.input_cache_tokens}")
print(f"输出令牌数: {llm.output_tokens}")

可用的统计信息：

• total_tokens - 使用的总令牌数（输入 + 输出）
• input_tokens - 提示/输入令牌的数量
• input_cache_tokens - 缓存的输入令牌数量（使用提示缓存时）
• output_tokens - 生成/完成令牌的数量

实时监控：

您还可以在翻译过程中实时监控令牌使用情况：

from tqdm import tqdm
import time

with tqdm(total=100, desc="翻译中", unit="%") as pbar:
    last_progress = 0.0
    start_time = time.time()

    def on_progress(progress: float):
        nonlocal last_progress
        increment = (progress - last_progress) * 100
        pbar.update(increment)
        last_progress = progress

        # 在进度条中更新令牌统计信息
        pbar.set_postfix({
            'tokens': llm.total_tokens,
            'cost_est': f'${llm.total_tokens * 0.00001:.4f}'  # 根据您的定价估算
        })

    translate(
        source_path="source.epub",
        target_path="translated.epub",
        target_language=language.ENGLISH,
        submit=SubmitKind.APPEND_BLOCK,
        llm=llm,
        on_progress=on_progress,
    )

    elapsed = time.time() - start_time
    print(f"\n翻译完成，耗时{elapsed:.1f}秒")
    print(f"总共使用的令牌数: {llm.total_tokens:,}")
    print(f"平均每秒使用的令牌数: {llm.total_tokens/elapsed:.1f}")

双LLM令牌跟踪：

当分别使用不同的LLM进行翻译和填充时，每个LLM都会跟踪各自的统计信息：

translation_llm = LLM(key="...", url="...", model="gpt-4", token_encoding="o200k_base")
fill_llm = LLM(key="...", url="...", model="gpt-4", token_encoding="o200k_base")

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,
    submit=SubmitKind.APPEND_BLOCK,
    translation_llm=translation_llm,
    fill_llm=fill_llm,
)

print(f"翻译使用的令牌数: {translation_llm.total_tokens}")
print(f"填充使用的令牌数: {fill_llm.total_tokens}")
print(f"合计总数: {translation_llm.total_tokens + fill_llm.total_tokens}")

注意： 令牌统计信息是LLM实例所有API调用的累计值。这些计数只会增加，并且在使用并发翻译时是线程安全的。

相关项目

PDF Craft

PDF Craft 可以将PDF文件转换为EPUB等格式，尤其擅长处理扫描版书籍。您可以将PDF Craft与EPUB Translator结合使用，将扫描版PDF书籍转换并翻译成双语EPUB格式。

工作流程：扫描版PDF → [PDF Craft] → EPUB → [EPUB Translator] → 双语EPUB

完整教程请观看：如何将扫描版PDF书籍转换为EPUB格式并翻译成双语书

贡献

欢迎贡献！请随时提交Pull Request。

许可证

本项目采用MIT许可证授权——详情请参阅LICENSE文件。

支持

• 问题：GitHub Issues
• 在线应用：Inkora - EPUB Translator

EPUB Translator 快速上手指南

EPUB Translator 是一款基于 AI 的开源工具，能够将任意 EPUB 电子书转换为双语对照版本。它在保留原文格式、图片和结构的同时，利用大语言模型生成侧边对照的译文，非常适合语言学习、学术研究或外文阅读。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows / macOS / Linux
• Python 版本：3.11, 3.12 或 3.13
• 依赖项：需具备访问大语言模型 API 的能力（如 OpenAI、Azure OpenAI 或其他兼容接口）

安装步骤

使用 pip 直接安装最新稳定版：

pip install epub-translator

提示：如果下载速度较慢，可以使用国内镜像源加速安装：

pip install epub-translator -i https://pypi.tuna.tsinghua.edu.cn/simple

如需进度条支持（可选），建议安装 tqdm：

pip install tqdm

基本使用

1. 初始化 LLM 客户端

首先，配置您的大语言模型 API 信息。以下以 OpenAI 为例：

from epub_translator import LLM

llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="o200k_base",
)

2. 执行翻译

使用 translate 函数将源文件翻译为目标语言。推荐采用 APPEND_BLOCK 模式，该模式会将译文作为独立段落附加在原文后，形成清晰的双语对照效果。

from epub_translator import translate, language, SubmitKind

translate(
    source_path="source.epub",
    target_path="translated.epub",
    target_language=language.ENGLISH,  # 目标语言，也可用字符串如 "Chinese"
    submit=SubmitKind.APPEND_BLOCK,    # 推荐模式：双语对照
    llm=llm,
)

3. 带进度监控的翻译（可选）

若需实时查看翻译进度，可结合 tqdm 使用回调函数：

from tqdm import tqdm

with tqdm(total=100, desc="Translating", unit="%") as pbar:
    last_progress = 0.0

    def on_progress(progress: float):
        nonlocal last_progress
        increment = (progress - last_progress) * 100
        pbar.update(increment)
        last_progress = progress

    translate(
        source_path="source.epub",
        target_path="translated.epub",
        target_language="Chinese",
        submit=SubmitKind.APPEND_BLOCK,
        llm=llm,
        on_progress=on_progress,
    )

运行完成后，您将在指定路径获得保留原格式的双语 EPUB 文件。