第三章：Web UI 界面操作详解

DocuTranslate 提供了一个开箱即用的 Web 界面，是普通用户最常用的入口。本章讲解界面的启动、各配置区域的含义，以及三类典型任务（论文翻译、小说翻译、Office 文档翻译）的操作要点。

由于 DocuTranslate 前端会随版本迭代，本章描述的是界面的功能区块与逻辑，具体按钮位置、文案可能与你的版本略有差异，请结合实际界面理解。

3.1 启动与访问

启动 Web 界面：

docutranslate -i

• 默认监听 127.0.0.1:8010，只能本机访问。
• 浏览器访问 http://127.0.0.1:8010。
• API 文档在 http://127.0.0.1:8010/docs。

若要让局域网内其他电脑 / 手机访问：

docutranslate -i --host 0.0.0.0 -p 8010

然后其他设备用 http://<本机局域网IP>:8010 访问。DocuTranslate 支持局域网多人同时使用，每个人的翻译任务相互独立、排入同一个后端任务队列。

3.2 界面整体布局

Web 界面大体分为几个功能区：

1. 模型配置区：填写大模型的 base_url、api_key、model_id，选择目标语言、并发数、思考模式等。
2. 文件上传区：选择或拖入要翻译的文件。DocuTranslate 会根据扩展名自动匹配工作流。
3. 解析引擎区（PDF 专用）：当上传的是 PDF 时，需要选择 PDF 解析引擎（MinerU 在线 / 本地部署）并填写相关参数。
4. 高级选项区：术语表、自定义提示词、分块大小、插入模式、JSON 路径等（随文件类型显示不同选项）。
5. 任务与进度区：显示翻译进度、日志，完成后提供多种格式的下载与在线预览。

3.3 模型配置区详解

这是使用前必须填写的部分（除非已通过环境变量预置了默认值，见第十一章）：

• base_url：AI 平台的基础地址，例如 DeepSeek 是 https://api.deepseek.com/v1，智谱是 https://open.bigmodel.cn/api/paas/v4。各平台地址见第四章表格。
• api_key：对应平台的密钥。
• model_id：模型名称，例如 deepseek-chat、glm-4-flash、qwen-plus、doubao-seed-1-6-flash 等。
• 目标语言（to_lang）：翻译成的语言，如「中文」「English」「日本語」。直接填语言的自然语言名称即可。
• 并发数（concurrent）：同时向大模型发起的请求数，默认 10。数值越大越快，但要注意平台的速率限制（RPM/TPM）。
• 思考模式（thinking）：控制模型是否使用「思考 / 推理」过程，一般文档翻译建议关闭以节省 token 与时间。

填好后建议先用一个很小的文件测试，确认模型连通、译文语言正确。

3.4 文件上传与自动识别

文件上传区支持选择或拖拽文件。DocuTranslate 会根据扩展名自动选择对应工作流：

各工作流的能力、输入输出格式详见第五章。

3.5 任务一：翻译学术论文（PDF）

论文翻译是 DocuTranslate 的招牌能力。要点：

1. 上传 PDF 文件。
2. 在解析引擎区选择 MinerU（在线，需要 Token）或 MinerU 本地部署。
3. 建议开启公式识别（formula_ocr）与代码识别（code_ocr），以正确处理论文中的公式和代码块。
4. 选择目标语言，点击开始。
5. 完成后可下载 HTML（推荐，公式、表格显示效果最好）、Markdown（含图片的 zip 或内嵌图片的 md）等格式。

重要提醒：PDF 会先被转换成 Markdown，原始排版会丢失，得到的是「内容忠实、版式重排」的译文。对版式有严格要求（如需要与原文逐页对照）的场景请注意。

MinerU Token 的申请与本地部署方法见第四章。

3.6 任务二：翻译小说 / 电子书（EPUB / TXT）

小说翻译（长文本）是另一个常见场景：

1. 上传 .epub 或 .txt 文件。
2. 无需 PDF 解析引擎，只需模型配置。
3. 长文本会被自动分块（由 chunk_size 控制）并并发翻译。
4. 对于篇幅很长的小说，建议：
   • 适当调大 concurrent 提升速度（注意平台速率限制）；
   • 如涉及大量人名、地名、专有设定，开启自动术语表或手动传入术语表，保证全书译名一致（见第八章）；
   • 用自定义提示词指定语气、风格（如「保持原文的文学性，人物对话口语化」）。
5. EPUB 可翻译后仍导出为 EPUB，保留章节结构。

3.7 任务三：翻译 Office 文档（Word / Excel）

DocuTranslate 支持 docx、xlsx 保持原格式翻译（不支持老式 doc、xls）：

• Word（docx）：可选择插入模式 insert_mode：
  • replace（替换，默认）：用译文替换原文；
  • append（追加）：在原文后追加译文（原文译文对照）；
  • prepend（前置）：在原文前插入译文。
• Excel（xlsx / csv）：同样支持插入模式；还可以指定翻译区域（如只翻译 Sheet1!A1:B10），避免翻译不需要的单元格。

对照模式（append/prepend）非常适合需要审校、双语对照的场景。

3.8 术语表与自定义提示词（界面侧）

在高级选项区，通常可以：

• 开启自动术语表生成：让模型先扫描全文提取术语并统一译法，再进行翻译。
• 上传 / 填写术语表：手动指定「原词 → 译词」映射（如 Jobs → 乔布斯），强制统一关键术语。
• 自定义提示词（custom_prompt）：追加你自己的翻译要求，例如指定风格、领域、保留某些不译的词等。

术语表和提示词的原理、编程用法详见第八章。

3.9 查看进度、下载与预览

任务提交后：

• 进度区会实时显示百分比进度和日志。若翻译出错（如欠费、网络问题），日志会给出报错信息。
• 完成后可在线预览译文（HTML 预览效果最佳），并下载多种格式。可下载的格式取决于文件类型对应的工作流（见第五章）。
• 后端对 PDF 的解析结果有内存缓存（默认最近 10 次），对同一 PDF 反复调参翻译时可以复用解析结果、避免重复解析（缓存数量由 DOCUTRANSLATE_CACHE_NUM 控制）。

3.10 小结

• Web 界面的核心流程：填模型配置 → 上传文件 → （PDF 才需要）配置解析引擎 → 开始翻译 → 下载译文。
• 论文用 MinerU + 开公式/代码识别；小说用分块并发 + 术语表；Office 文档用保持格式 + 插入模式。
• 界面上的每一项配置，背后都对应 SDK / API 的一个参数，理解了界面也就理解了后续编程接口。
• 下一章我们专门讲最容易卡住新手的两块配置：大模型 API 与 PDF 解析引擎。