CLAUDE.md (中文版)

此文件为 Claude Code (claude.ai/code) 在本代码库中工作时提供指导。

项目概述

这是一个EPUB翻译项目，用于将英文书籍转换为中文。系统从EPUB档案中提取HTML文件，使用各种AI翻译API（DeepSeek、SiliconFlow等）处理和翻译内容，并在SQLite数据库中维护翻译进度。

架构设计

核心组件

翻译引擎: /code/ 目录中的主要翻译脚本，处理批量翻译并跟踪进度
HTML处理: 用于EPUB结构的HTML内容提取和清理工具
配置管理: 基于YAML的配置系统，用于API密钥、翻译设置和数据库路径
进度跟踪: SQLite数据库系统，跟踪文件和翻译组的进度
EPUB结构: 组织的目录(001/, 003/, 004/)，包含不同EPUB提取物，HTML文件位于/Ops/子目录中

主要翻译脚本

translate_epub_v4(单线程版本)V3.py - 原始稳定的单线程翻译脚本
translate_epub_v4_optimized.py - 推荐优化版本，具有批量数据库操作和翻译缓存
translate_epub.py - 带异步处理的多线程版本
main.py - 简单的API测试脚本

HTML处理

文件按EPUB结构组织：META-INF/、Ops/(HTML内容)、images/
HTML文件包含带CSS类的结构化内容（主要是段落的p34类）
处理脚本清理并准备HTML进行翻译，同时保持结构

常用命令

运行翻译

# 推荐：带缓存和批量操作的优化版本（智能跳过已翻译文件）
python code/translate_epub_v4_optimized.py

# 强制重新翻译所有文件（覆盖已存在的文件）
python code/translate_epub_v4_optimized.py --force

# 查看所有可用选项
python code/translate_epub_v4_optimized.py --help

# 原始稳定版本
python code/translate_epub_v4(单线程版本)V3.py

# 多线程版本
python code/translate_epub.py

# 性能对比测试
python code/performance_test.py

进度监控

# 检查翻译进度
sqlite3 translation_progress.db "SELECT * FROM translation_progress;"

# 详细文件进度
sqlite3 translation_progress.db "SELECT file_path, ROUND(processed_lines * 100.0 / total_lines, 2) as progress_percent, status, last_updated FROM file_progress;"

# 翻译组进度
sqlite3 translation_progress.db "SELECT file_path, group_index, status, updated_at FROM group_progress ORDER BY file_path, group_index;"

# 检查翻译缓存效果（优化版本）
sqlite3 translation_progress.db "SELECT COUNT(*) as cached_translations, AVG(access_count) as avg_reuse FROM translation_cache;"

依赖安装

# 安装所需包
pip install -r code/requirements.txt

配置

API配置

系统支持在code/config.yaml中配置多个AI翻译提供商：

DeepSeek API（默认：deepseek-chat模型）
SiliconFlow API
Zhipu API（GLM模型）

翻译设置

可配置的批量大小（最小：3行，最大：10行每请求）
带重试逻辑和冷却期的错误处理
并发请求限制和超时设置
翻译缓存以避免重复翻译相同内容

数据库架构

translation_progress: 总体进度跟踪
file_progress: 按文件翻译状态
group_progress: 翻译组/批次状态
translation_cache: 缓存的翻译（仅优化版本）
line_progress: 单行翻译跟踪

优化特性 (translate_epub_v4_optimized.py)

性能增强

智能文件跳过: 自动检测并跳过已翻译的文件，避免重复工作
批量数据库操作: 将多个数据库写入合并为单个事务（数据库操作快20倍）
多级翻译缓存:
- 内存缓存（LRU）用于即时访问
- 持久化数据库缓存用于会话恢复
- 基于文件的缓存备份
智能进度恢复: 从中断点高效恢复
优化的SQLite设置: WAL模式、增大缓存大小、内存临时存储
命令行选项: 支持强制重新翻译、跳过缓存等高级功能

缓存系统优势

避免在文件间重复翻译相同内容
持久化缓存在脚本重启后保留
相似内容的缓存命中率通常为30-60%
自动清理旧的未使用条目

监控与统计

实时性能指标
缓存效果报告
数据库操作统计
翻译速度跟踪

文件组织

输入HTML文件：位于编号目录(001/, 003/, 004/)的/Ops/子目录下
翻译输出：通常保存到*_translated/目录
归档版本：历史翻译脚本版本存储在/code/归档/中
配置：YAML文件在/code/目录中
缓存文件：存储在/cache/目录中（优化版本）

性能优化建议

高优先级优化

使用优化版本脚本: translate_epub_v4_optimized.py提供最佳性能
调整批量大小: 在config_optimized.yaml中根据硬件调整batch_commit_size
监控缓存效果: 定期检查缓存命中率，高重复内容项目收益明显

配置调优

initial_line_count: 每组处理行数，增大可提速但可能影响质量
cache_size: 内存缓存大小，根据可用内存调整
batch_commit_size: 数据库批量提交大小，较大值提升性能

故障排除

# 检查缓存统计
sqlite3 translation_progress.db "SELECT * FROM translation_cache LIMIT 10;"

# 查看错误日志
tail -f translation.log

# 重置进度（谨慎使用）
sqlite3 translation_progress.db "DELETE FROM file_progress WHERE status != 'completed';"

开发提示

修改翻译提示词请编辑脚本中的system消息内容
支持多种编码格式的HTML文件（utf-8, gbk, gb2312, latin1）
使用流式输出实时显示翻译进度
支持键盘中断时的优雅退出和进度保存

性能基准

使用优化版本相比原版本的典型改进：

数据库操作速度：提升20-50倍
整体翻译速度：提升30-70%（取决于内容重复率）
内存使用：更高效的缓存策略
API调用次数：通过缓存显著减少

提示: 对于新项目，建议直接使用translate_epub_v4_optimized.py以获得最佳性能和用户体验。

CLAUDE_CN.md 6.1 KB Permalink History Raw