docutranslate/CLAUDE.md

DocuTranslate（华宝/langcore 分支）运维指南

本仓库 fork 自 xunbu/docutranslate，已针对华宝（印尼烟厂）的中文/英文/印尼语三语文档翻译场景定制。

Git 仓库

• 远程地址：https://git.langcore.net/Leon/docutranslate
• 账号：leon@langcore.cn
• 默认分支：main（所有修改提交到 main 并推送）

客户服务器更新步骤

客户服务器运行在 Windows 上，部署路径 C:\Users\langcore3\Desktop\doctranslate\docutranslate，对外地址 http://172.16.100.246:8010/。

# 1. 进入项目目录
cd C:\Users\langcore3\Desktop\doctranslate\docutranslate

# 2. 拉取最新代码
git pull

# 3. 确认已拉到目标提交
git log --oneline -1

# 4. 重启服务（先 Ctrl+C 停掉当前运行的 uv run docutranslate，再启动）
uv run docutranslate -i --host 0.0.0.0

--host 0.0.0.0 是必须的，否则服务只监听 127.0.0.1，局域网其他设备无法访问（这是常见的"外部访问不到"原因）。

启动后验证

# 健康检查（应返回版本号）
python -c "import urllib.request,json; print(urllib.request.urlopen('http://127.0.0.1:8010/service/meta').read().decode())"

# 共享术语表（应返回 {"rows":[...]}）
python -c "import urllib.request,json; print(urllib.request.urlopen('http://127.0.0.1:8010/service/glossary').read().decode())"

浏览器侧：访问 http://172.16.100.246:8010/ 后 Ctrl+Shift+R 硬刷新，清除旧的 JS/CSS/JSON 缓存。

翻译 API 配置

.env 文件（项目根目录，不入 git）配置 LLM 凭证：

DOCUTRANSLATE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
DOCUTRANSLATE_API_KEY=<阿里云 DashScope Key>
DOCUTRANSLATE_MODEL_ID=qwen3.6-plus   # 或 qwen-mt-plus
DOCUTRANSLATE_RPM=
DOCUTRANSLATE_TPM=

• DashScope API Key 受 IP/账号绑定：在客户服务器上可用的 Key，从开发机或命令行测试可能返回 401（这是正常的，不是 Key 失效）。只在客户服务器上验证 Key。
• qwen-mt-plus（MT 模型）：会破坏所有文本分隔符/JSON 结构，只能逐条翻译，速度慢（616 段 ~14 分钟）。推荐用 qwen3.6-plus（通用大模型，JSON 批处理，~1 分钟）。
• RPM/TPM 留空：非 MT 模型不需要限流。

关键数据目录

• data/glossary.json — 全公司共享三语术语表（运行时生成，已 gitignore，各服务器独立存储）
• docutranslate/output/ — 翻译输出临时目录（已 gitignore）
• .env — API 凭证（已 gitignore）

本地开发

# 开发模式启动（仅本机访问，默认端口 8010）
uv sync
uv run docutranslate -i

本地可用的测试 LLM（智谱 GLM，与 DevScope 项目共用 Key）：

DOCUTRANSLATE_BASE_URL=https://open.bigmodel.cn/api/paas/v4
DOCUTRANSLATE_API_KEY=9a0a338f1ef346f293733201b96335cd.Guv1hBOyqopJHOjh
DOCUTRANSLATE_MODEL_ID=glm-4-flash

本分支相对原项目的关键改动

• 共享三语术语表（中/英/印尼）：glossary/glossary_store.py + glossary/lang_mapping.py + GET/POST /service/glossary，全公司共享、保存即生效、默认引用。
• MT 模型逐条翻译：segments_agent.py 对 qwen-mt-* 模型改用纯文本逐条发送（MT 模型会破坏批处理分隔符）。
• docx 格式保留：docx_translator.py 段落级翻译 + 合并同格式 Run，Run 保留率从 3.8% 提升到 ~100%。
• 多语言 UI：中文/English/Bahasa Indonesia（替换原越南语），浏览器语言自动检测。