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

本仓库 fork 自 [xunbu/docutranslate](https://github.com/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/`。

```powershell
# 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，局域网其他设备无法访问（这是常见的"外部访问不到"原因）。

### 启动后验证

```powershell
# 健康检查（应返回版本号）
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 凭证：

```env
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）

## 本地开发

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

本地可用的测试 LLM（智谱 GLM，与 DevScope 项目共用 Key）：
```env
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（替换原越南语），浏览器语言自动检测。
