# 翻译模块说明（Qwen / DeepL）

本文档汇总翻译模块的**接口使用说明**与**Python 模块用法**，对应代码：

- HTTP 服务：`api/translator_app.py`
- Python 模块：`query/translator.py`

---

## 1. 功能概述

当前翻译模块支持两种后端：

- **Qwen（默认）**：通过阿里云百炼 DashScope 的 OpenAI 兼容接口调用 `qwen-mt-flash`
- **DeepL**：通过 DeepL API 调用翻译（保留原有能力）

两种方式均支持：

- **Redis 缓存**（如启用）：同文案同目标语言命中缓存直接返回
- **`source_lang` 自动检测**：当 `source_lang` 为空或 `"auto"` 时启用自动检测（Qwen 使用 `"auto"`）

---

## 2. 环境变量与配置

项目会在 `config/env_config.py` 中加载项目根目录的 `.env`，常用变量如下：

```env
# Qwen / DashScope
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx

# 可选：翻译服务默认模型（HTTP 服务启动后若请求不传 model，则使用此默认值）
TRANSLATION_MODEL=qwen  # 或 deepl
```

说明：

- **Qwen** 使用 `DASHSCOPE_API_KEY`
- **DeepL** 使用 `DEEPL_AUTH_KEY`
- `.env` 中的 `OPENAI_API_KEY` 不是本翻译模块必须项（当前实现用的是 `DASHSCOPE_API_KEY`）

---

## 3. HTTP 翻译服务（`api/translator_app.py`）

### 3.1 启动命令

推荐（热更新）：

```bash
cd /home/tw/SearchEngine
uvicorn api.translator_app:app --host 0.0.0.0 --port 6006 --reload
```

指定默认模型（不传请求 `model` 时生效）：

```bash
cd /home/tw/SearchEngine
export TRANSLATION_MODEL=qwen   # 或 deepl
uvicorn api.translator_app:app --host 0.0.0.0 --port 6006 --reload
```

### 3.2 接口列表

- **GET** `/health`：健康检查（返回默认模型、已初始化模型列表等）
- **POST** `/translate`：翻译文本
- **GET** `/docs`：Swagger UI

### 3.3 `/translate` 请求参数

请求体（JSON）：

```json
{
  "text": "要翻译的文本",
  "target_lang": "en",
  "source_lang": "auto",
  "model": "qwen"
}
```

- **text**：必填，待翻译文本
- **target_lang**：必填，目标语言代码（见“语言支持”）
- **source_lang**：可选，源语言代码；不传或传 `"auto"` 时自动检测
- **model**：可选，`"qwen"` 或 `"deepl"`；默认 `"qwen"`

### 3.4 `/translate` 返回参数

响应体（JSON，成功时）：

```json
{
  "text": "商品名称",
  "target_lang": "en",
  "source_lang": "zh",
  "translated_text": "Product name",
  "status": "success",
  "model": "qwen"
}
```

### 3.5 请求示例（curl）

健康检查：

```bash
curl http://localhost:6006/health
```

默认（qwen）中文 → 英文：

```bash
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"我看到这个视频后没有笑","target_lang":"en","source_lang":"auto"}'
```

显式指定 qwen，英文 → 简体中文：

```bash
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Product name","target_lang":"zh","source_lang":"en","model":"qwen"}'
```

繁体中文（`zh_tw`）测试：

```bash
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"商品名稱","target_lang":"zh_tw","source_lang":"auto","model":"qwen"}'
```

切换 DeepL：

```bash
curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"商品名称","target_lang":"en","source_lang":"zh","model":"deepl"}'
```

### 3.6 关于提示词（Prompt）

HTTP 服务内部使用了固定提示词 `TRANSLATION_PROMPT`（适用于“商品 SKU 英文名”场景），并通过 `prompt` 参数传入 `Translator.translate()`。

- **DeepL**：`prompt` 会作为 DeepL 的 `context` 使用（影响翻译但不被翻译）
- **Qwen**：当前实现未将 `prompt/context` 传给 Qwen 的 `translation_options`（即对 Qwen 不生效）

---

## 4. Python 翻译模块（`query/translator.py`）

### 4.1 基本用法

```python
from query.translator import Translator

# 默认使用 qwen
translator = Translator()

result = translator.translate(
    text="我看到这个视频后没有笑",
    target_lang="en",
    source_lang="auto",
)
print(result)
```

显式选择模型：

```python
translator_qwen = Translator(model="qwen")
translator_deepl = Translator(model="deepl")
```

### 4.2 关键参数

- `Translator(model="qwen" | "deepl")`：选择翻译模型，默认 `"qwen"`
- `translate(text, target_lang, source_lang=None, context=None, prompt=None)`：
  - `target_lang` / `source_lang`：语言代码（见“语言支持”）
  - `source_lang` 为空或 `"auto"`：自动检测
  - `prompt`：
    - DeepL：作为 `context` 使用
    - Qwen：当前未使用

### 4.3 缓存（Redis）

`Translator(use_cache=True)` 时会连接 Redis 并缓存翻译结果。

- Redis 连接配置来自 `config/env_config.py` 的 `REDIS_CONFIG`
- 缓存 key 前缀默认 `trans`（可用 `REDIS_TRANSLATION_CACHE_PREFIX` 覆盖）

---

## 5. Qwen 语言支持（按 qwen-mt-plus/flash/turbo 标准）

> 以下为 Qwen 翻译模型支持的语言（**代码 → 英文名**），并已用于 `query/translator.py` 的映射。

| 代码 | 英文名 |
|------|--------|
| en | English |
| zh | Chinese |
| zh_tw | Traditional Chinese |
| ru | Russian |
| ja | Japanese |
| ko | Korean |
| es | Spanish |
| fr | French |
| pt | Portuguese |
| de | German |
| it | Italian |
| th | Thai |
| vi | Vietnamese |
| id | Indonesian |
| ms | Malay |
| ar | Arabic |
| hi | Hindi |
| he | Hebrew |
| my | Burmese |
| ta | Tamil |
| ur | Urdu |
| bn | Bengali |
| pl | Polish |
| nl | Dutch |
| ro | Romanian |
| tr | Turkish |
| km | Khmer |
| lo | Lao |
| yue | Cantonese |
| cs | Czech |
| el | Greek |
| sv | Swedish |
| hu | Hungarian |
| da | Danish |
| fi | Finnish |
| uk | Ukrainian |
| bg | Bulgarian |

---

## 6. 常见问题（FAQ）

### 6.1 Qwen 调用报错 / 无法初始化

- 确认 `.env` 中已配置 `DASHSCOPE_API_KEY`
- 确认安装依赖：`openai`（Python 包）
- 如在海外地域使用模型，将 `base_url` 切换为 `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`

### 6.2 DeepL 返回 403 / 翻译失败

- 确认 `.env` 中已配置 `DEEPL_AUTH_KEY`
- 若使用的是 Pro key，请使用 `https://api.deepl.com/v2/translate`（当前代码即为该地址）