Precise AI translation method with noun comparison list.
中文 | English
我们持续优化了程序的健壮性与交互体验，新增了针对异常场景的全面保护机制，并完善了术语动态管理功能：
- 交互式故障恢复：当 API 连续失败次数达到上限时，程序不再直接退出，而是暂停并提供选项：用户可选择“重置失败计数并继续重试”或“保存当前进度后退出”。
- 手动中断保护：捕获
Ctrl+C中断信号，确保在用户手动停止程序时，能够安全保存已累积的术语表和剩余未翻译的原文。 - 断点续传支持：程序自动定位并保存未翻译部分为
_rest.md文件，方便后续继续翻译。 - API 内容自动修复：针对 API 返回的 JSON 格式错误，实现了自动检测与段落级重试机制，防止因单次解析失败导致程序崩溃。
- CLI 偏好记忆：启动时自动加载上次使用的 API 平台、文件路径等配置，直接回车即可沿用。
- 术语并集匹配：翻译过程中实时收集“新术语”，与 CSV 词表形成并集参与匹配，最大化术语命中率。
- 可控合并开关：翻译结束或中断时，用户可交互选择是否将新收集的术语合并到原词表中；不合并也会自动导出为独立 CSV 文件（
原文件名_时间戳.csv）。 - 专有名匹配优化：对全大写/首字母大写的专有名（如 HOPKINS/Hopkins）进行更稳健的大小写规整。
- 程序稳定性：当前版本的程序仍在不断完善中，可能存在一些 bug 或不足。如果您在使用过程中遇到任何问题，欢迎及时反馈，我们会尽快解决。
- API请求耗时过长：由于调用大模型API需要一定的时间，因此在翻译长篇文档时，可能会出现API请求耗时过长的情况。我们会在后续版本中优化这一问题。
- 提示词需要优化：当前版本的提示词可能不够完善，导致翻译效果不佳。我们需要更多人的使用与意见反馈，才能在后续版本中不断优化提示词，提升翻译质量。
计划变更：由于“空白术语表生成功能”当前效果不佳，已决定暂时下架，后续视情况重构或不再提供。
AIwork4translator 是一个专业的文档翻译工具，通过专有名词识别和正则过滤方法，确保大模型翻译时准确使用专业术语。它能够智能处理各种格式的技术文档，保留原文格式和专有名词，提供高质量的翻译结果。
- 专有名词识别与保护：使用 Aho-Corasick 自动机高效匹配术语，支持复数归一化与冠词智能处理，确保术语在翻译中保持一致。
- 术语动态管理（重构核心）：在长篇文档翻译过程中，实时采集“新术语”并与词表形成并集参与匹配；支持“是否合并新术语到词表”的交互开关；遇到短暂 API 波动自动进行段落级重试，显著提升稳定性与一致性。
- 多格式支持：支持
.txt和.md格式文件的翻译，通过MarkItDown工具还可以支持PDF、PowerPoint、Word、Excel、HTML等更多格式 - 多种翻译引擎：支持多种API翻译引擎，包括OpenAI、Kimi、DeepSeek、Ollama等
- 命令行与WebUI双模式：提供命令行和Web界面两种使用方式，满足不同场景需求
- CLI 偏好记忆：命令行版本自动记录上次使用的 API 平台与文件路径，提升交互效率。
- 双栏Markdown编辑器：WebUI中提供左右分栏的原文/译文实时展示功能
- 实时翻译进度展示：翻译过程中实时显示当前处理的段落数/总段落数
- 中断保护与恢复：支持 Ctrl+C 安全中断，自动保存进度与未翻译内容
- 交互式故障恢复：API 连续失败时提供暂停与重试选项，防止任务意外终止
- 轮询机制：采用高效的轮询机制，实时获取并更新翻译进度和内容
- 自动保存功能：翻译完成后自动检测并保存用户修改
- 交互式确认：非Markdown文件转换后提供用户确认环节，确保转换质量
- 空白名词表生成：可自动识别原文中的实体名词并生成空白名词表（命令行版本）（注意：该功能计划将在近期暂时下架，详见下文“开发计划”）
- 结构化/非结构化翻译模式：支持基于Markdown标题结构的智能分段处理
project_root/
├── data/
│ └── .env
├── models/
│ └── dbmdz/bert-large-cased-finetuned-conll03-english-for-ner/
│ ├── config.json
│ ├── gitattributes
│ ├── model.safetensors
│ ├── special_tokens_map.json
│ ├── tokenizer.json
│ ├── tokenizer_config.json
│ └── vocab.txt
├── modules/ # 统一的业务模块
│ ├── __init__.py
│ ├── api_tool.py # LLMService 与各供应商适配（返回content,tokens）
│ ├── config.py # GlobalConfig（env优先），不含会话缓存
│ ├── count_tool.py
│ ├── csv_process_tool.py # Aho-Corasick 匹配与 CSV 校验
│ ├── markitdown_tool.py
│ ├── ner_list_tool.py # 稳健模型查找，优先根 models/
│ ├── read_tool.py
│ └── write_out_tool.py # 默认不写 “# end”
├── templates/
│ ├── index.html
│ └── editor.html
├── static/
│ ├── style.css
│ ├── script.js
│ └── editor.js
├── uploads/ # WebUI 上传与输出目录（由后端挂载）
├── app.py # WebUI 根入口（提供 main()）
├── main.py # CLI 根入口（交互式，支持偏好持久化）
├── baseline.py # CLI 基线示例（不含RAG缓存）
├── ner_list_check.py # NER 生成名词表工具
└── pyproject.toml # 脚本入口：CLI/WebUI本项目的核心是在翻译前后对专有名词进行智能识别与约束。我们通过 Aho-Corasick 算法与正则在段落中捕捉术语，并在提示词中显式要求模型遵循这些译名，从而提升术语一致性与可审阅性。系统支持复数形式自动归一化（如 "outlaws" -> "outlaw"）及灵活的冠词匹配（如 "the Outlaw" 可匹配 "an outlaw"）。与传统 RAG 方案相比，初步测试显示：额外 token 开销可减少约 99%，术语命中数量提升约 35%，整体译文质量因术语准确度提升而更稳定。
同时，任何词表都不可能覆盖文本中的所有新术语。为此，系统会在翻译结果中自动汇总并标注未覆盖的新名词，便于编辑审核与补充词表。
推荐的使用方式：输入 Markdown 原文与 CSV 词表，输出为 Markdown 译文。对于非 Markdown 文件，该程序会自动识别并使用 MarkItDown 转换后再翻译。感谢 MarkItDown 的贡献；目前 PDF（非 OCR）表现良好，OCR PDF 仍待进一步验证。
也可以使用通过 MinerU 解析获得的 Markdown 文件作为输入，程序对此的适配良好。
Python:3.10-3.13- 使用
uv进行依赖管理：在项目根目录执行uv sync（默认创建并使用.venv） - 激活虚拟环境（Windows：
\.venv\Scripts\activate） - 修改
data\.env中的环境变量，配置 API KEY 等 - 运行根入口
uv run main.py，按提示选择供应商与文件路径 - 新增/卸载依赖：
uv add <package>/uv remove <package> - 运行
python -m pytest执行测试（用例已绑定根入口与资源）。
- 配置与密钥：在
data/.env配置 API KEY，切勿提交到仓库；连续 API 失败≥3次时，运行 CLI 的 API 测试并检查网络/代理。默认 Kimi：BASE_URL=https://api.moonshot.cn/v1、MODEL=kimi-k2-turbo-preview。 - 词表质量与性能：CSV 必须两列、UTF-8、无空行、原文列唯一。大规模词表会增加匹配耗时，但得益于 Aho-Corasick 优化，数千条术语仍能毫秒级匹配。支持多词术语与复数形式。
- 交互偏好：CLI 会自动记录上次使用的 API 平台与文件路径（存储于
data/.prefs.json），下次启动时通过[...]提示预填充，直接回车即可沿用。 - 输入与结构：优先提供原生 Markdown；非 Markdown 会自动转换，转换后请人工校对再继续。结构化模式依赖标题层级，建议合理使用
#/##标题。 - 段落与大文件：超长段落会被智能拆分；极大文件处理时间较长，WebUI 建议≤10MB；CLI 进度以“当前/总段落”显示，请耐心等待。
- 翻译一致性：为提高术语一致性，建议降低
temperature；提示词已显式注入术语对照以提升稳定性。 - 本地模型：如使用 Ollama，请在
.env设置OLLAMA_BASE_URL与OLLAMA_MODEL，首次使用需确认服务已启动。 - 日志与输出：CLI 打印“共耗时：x时x分x秒”；统计表
counting_table.csv记录原始秒数与 tokens；WebUI 终端输出带时间戳。
当处理非Markdown格式文件时，程序会先将其转换为Markdown格式。转换完成后，程序会暂停并显示以下信息：
- 生成的Markdown文件路径
- 文件大小和段落数量
- 提示用户输入
y继续翻译，或输入n退出程序
示例提示信息：
文件转换完成，路径为【d:\BaiduSyncdisk\桌游\program_translator\data\test_file_output.md】，字数为【1500】，段落数量为【20】，是否继续翻译？如果选择n将结束程序。(y/n)
翻译过程中，系统会实时显示当前翻译进度：
正在翻译段落【当前段落数】/【总段落数】
-
如果没有csv格式的名词表，输入
n，程序会自动创建一个空白的名词表文件。- 文件名格式：
[原文件名]_output_terminology.csv - 你可以在翻译结束后（或中断后）填写该文件，以便下次使用。
- 注：基于NER的自动生成功能暂时下架。
- 文件名格式：
-
如果已有csv格式的名词表，输入
y进入名词表文件上传流程。- 输入csv格式的名词表文件路径（支持直接输入
.xlsx文件路径，程序会自动转换）。 - 新术语合并选项：
- 输入路径后，程序会询问“是否将新术语合并到术语表？(y/n)”。
- 选择
y：新发现的术语将直接追加到你提供的原CSV文件中（去重合并），并另存为备份。 - 选择
n：新术语将单独保存为一个新的CSV文件，不影响原文件。
- 输入csv格式的名词表文件路径（支持直接输入
- 确保在
\data文件夹中修改环境变量，将API_KEY更换为你自己的 - 开发过程中主要使用kimi进行测试，其他翻译引擎的API访问代码未充分测试
- 对于本地Ollama模型，需要修改
\data\.env中的OLLAMA_BASE_URL与OLLAMA_MODEL配置
- 修改根
data\.env中的环境变量，配置 API KEY 等 - 运行根入口
uv run app.py或脚本program-translator-webui - 打开终端返回的链接，或直接在浏览器中输入
http://localhost:8008/ - 首页上传
.md与.csv验证后，点击“使用双栏编辑器”，在编辑器页面点击“开始翻译”。 - 验证端点：
/validate-file、/start-translation、/translation-progress、/save-content、/download、/open-file。 - 在界面中依次点击“选择文件”与“验证文件/词典”，等待成功提示
- 选择所使用的API供应平台与模型
- 点击“开始处理文本”按钮，系统会开始处理文本并跳转到双栏编辑器页面
- 在双栏编辑器页面，点击“开始翻译”按钮启动翻译过程
- 翻译过程中，可以在右侧编辑器实时查看翻译进度和结果
- 翻译完成后，可以直接在右侧编辑器编辑内容
- 系统会自动保存内容，也可以使用
Ctrl+S快捷键手动保存
- 左侧编辑器：显示原文内容，默认为只读模式
- 右侧编辑器：实时显示翻译结果，支持编辑
- 进度显示：在翻译过程中显示当前处理的段落数/总段落数
- 自动保存：翻译结束后，每隔约20秒自动检查并保存内容变更
- 宽度调节：可通过拖拽两个编辑器中间的分隔线调整宽度
- 系统采用5秒间隔的轮询机制，实时从后端获取翻译进度和新内容
- 轮询过程中，只更新新增的翻译内容，避免整个文档重新加载
- 翻译完成后，轮询自动停止
WebUI 使用 FastAPI 框架开发，主要文件位于根目录：
核心文件：
app.py: Web 应用主入口，包含路由定义与 API 实现templates/index.html: 主页面模板templates/editor.html: 双栏编辑器页面模板static/style.css: 样式文件static/script.js: 前端交互逻辑static/editor.js: 编辑器与轮询逻辑
主要API端点：
/: 首页，展示上传表单/validate-file: 文件验证与格式转换接口/process: 处理参数并跳转到编辑器页面/editor: 双栏编辑器页面/start-translation: 启动翻译任务接口/translation-progress: 查询翻译进度和内容接口/save-content: 保存编辑器内容接口/download: 下载结果文件接口/open-file: 打开文件接口/load-content: 加载文件内容接口/test-api: LLM API连接测试接口
界面截图
下载页面：在右键菜单中选择“另存为”即可。
- 文件大小不应超过10MB
- 过大的文件可能导致处理时间较长，请耐心等待
- 对于格式复杂的文件，可能需要先手动转换为Markdown格式，以获得更好的翻译效果
| 原文 | 译文 |
|---|---|
| …… | …… |
| …… | …… |
在提供名词表后，程序设置了严格的审核步骤以确保名词表可以被正确使用。你可以提前确保以下几个标准以减少在这个步骤中需要花费的时间：
1. 确保文件无空行与空值。
2. 确保原文列无重复值。
3. 确保可以用“UTF-8”解码。- 文档应采用Markdown格式编写
- 文档中不包含目录，可能在切分中被误识别为段落。
- 文档中应包含标题（H1-H6），用于组织文档结构——标题与标题之间最好写有正文，否则可能在切分中被误识别为段落，导致模型不能正常翻译。
- 文档中每个标题上方有至少2个空行，用于分隔不同段落。
- 文档中不建议包含链接（文本），可能在切分中被损坏。
- 文档中不建议包含图片（
），可能在切分中被损坏。
-
非结构化翻译模式：适用于由Markitdown工具转换的非MD文件
- 不会识别MD文档的标题结构
- 适用于格式较为简单的文档
-
结构化翻译模式：适用于原生MD文件
- 默认识别文件中最多6级的标题结构
- 智能根据文本结构进行文段切割
- 默认分行符号为两个换行符号
已支持Ollama本地部署模型的接入。通过修改\data\.env中的以下配置来调用本地模型：
OLLAMA_BASE_URL: Ollama服务的URLOLLAMA_MODEL: 要使用的模型名称
# 同步项目依赖（默认 .venv）
uv sync
# 安装或卸载依赖
uv add <package>
uv remove <package>
# 运行 CLI
uv run main.py
# 运行 WebUI
uv run app.py
# 运行测试
python -m pytest.env位于根data/.env；默认 LLM 配置：KIMI_BASE_URL=https://api.moonshot.cn/v1KIMI_MODEL=kimi-k2-turbo-preview- 建议参数：
max_tokens=2048、temperature=0.7、top_p=0.95。 - 请务必安全保存 API KEY，不要提交到仓库。
- 已合并
src/与webui_project/到根结构；删除旧目录以减少路径混淆。 - 统一模块到根
modules/，移除 RAG 缓存；WebUI 与 CLI 对齐返回值与写出策略（平铺默认不写# end）。 - 脚本入口更新为根：
program-translator-cli = "main:main"、program-translator-webui = "app:main"。
- 1.2.0 版本：基础功能完成，包括 CLI、WebUI、模型支持等。
- 未来版本：
- 计划通过MinerU增强对Markdown文件的解析性能。
- 计划实现传统CAP软件的交互模式，例如表格形式的翻译界面，原文与译文逐句对应，用户可以方便地进行编辑和修改。
- 段落切分策略改进：更优雅地处理短段落和长难句，避免模型翻译时出现不自然的断句。
计划添加对术语表实时更新的功能，在文档中识别到陌生术语后会自动添加到术语表中，用户可以在翻译过程中实时查看和更新术语表。已完成：术语动态管理（并集匹配、合并开关、收集新术语与导出）。计划增强空白术语表的生成效果，除了实体类型外，还提供术语的翻译建议，帮助用户更准确地翻译文档。新计划：暂时下架“空白术语表生成”功能，因当前效果不佳；后续视情况重构或不再提供。
对于该程序有更多想法或遇到部署问题可以发信至chasen0315@gmail.com。最迟24小时内（截止2025/12/29）会进行回复。