# 翻译模块说明（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`（当前代码即为该地址）