# 翻译模块

  **快速上手**：见 `docs/QUICKSTART.md` 第 3.4 节。

  ## 环境变量

  ```bash
  # Qwen（默认）

  DASHSCOPE_API_KEY=sk-xxx
  
  # DeepL
  DEEPL_AUTH_KEY=xxx
  

  # 可选

  TRANSLATION_SERVICE_URL=http://127.0.0.1:6006
  TRANSLATION_MODEL=llm   # 默认能力；也可传 qwen-mt / deepl
  TRANSLATION_SCENE=general

  ```
  

  > **重要限速说明（Qwen 机翻）**  
  > 当前默认的 Qwen 翻译后端使用 `qwen-mt-flash` 云端模型，**官方限速较低，约 RPM=60（每分钟约 60 请求）**。  
  > - 推荐通过 Redis 翻译缓存复用结果，避免对相同文本重复打云端  
  > - 高并发场景需要在调用端做限流 / 去抖，或改为离线批量翻译  
  > - 如需更高吞吐，可考虑 DeepL 或自建翻译服务
  

  ## 配置模型
  
  翻译已改为“一个翻译服务 + 多种翻译能力”的结构：
  
  - 业务侧（`QueryParser` / indexer）统一调用 `http://127.0.0.1:6006`
  - 服务内按 `services.translation.capabilities` 加载并管理各翻译能力
  - 每种能力独立配置 `enabled`、`model`、`timeout` 等参数
  - 外部接口通过 `model + scene` 指定本次使用哪种能力、哪个场景
  
  配置入口在 `config/config.yaml -> services.translation`，核心字段示例：
  
  ```yaml
  services:
    translation:
      service_url: "http://127.0.0.1:6006"
      default_model: "llm"
      default_scene: "general"
      timeout_sec: 10.0
      capabilities:
        qwen-mt:
          enabled: true
          model: "qwen-mt-flash"
        llm:
          enabled: true
          model: "qwen-flash"
        deepl:
          enabled: false
  ```

  
  ## HTTP 接口契约（translator service，端口 6006）
  
  服务默认监听 `http://localhost:6006`，提供：
  
  - `POST /translate`: 文本翻译（支持 `qwen/qwen-mt`、`deepl`、`llm`）
  - `GET /health`: 健康检查
  
  ### `POST /translate`
  
  **请求体**：
  
  ```json
  {
    "text": "商品名称",
    "target_lang": "en",
    "source_lang": "zh",

    "model": "qwen-mt",
    "scene": "sku_name",

    "prompt": null
  }
  ```
  
  - `text` 支持两种形式：
    - 单条：`string`
    - 批量：`string[]`（等长返回，顺序对应）
  
  **响应体**（单条）：
  
  ```json
  {
    "text": "商品名称",
    "target_lang": "en",
    "source_lang": "zh",
    "translated_text": "Product name",
    "status": "success",

    "model": "qwen-mt",
    "scene": "sku_name"

  }
  ```
  
  **响应体**（批量）：
  
  ```json
  {
    "text": ["商品名称1", "商品名称2"],
    "target_lang": "en",
    "source_lang": "zh",
    "translated_text": ["Product name 1", null],
    "status": "success",

    "model": "qwen-mt",
    "scene": "sku_name"

  }
  ```
  
  批量模式下，**单条失败用 `null` 占位**（即 `translated_text[i] = null`），保证长度与顺序一一对应，避免部分失败导致整批报错。
  

  说明：
  
  - `scene` 是标准字段，`context` 仅保留为兼容别名
  - `model` 只能选择已在 `services.translation.capabilities` 中启用的能力
  - `/health` 会返回 `default_model`、`default_scene` 与 `enabled_capabilities`
  

  ---
  

  ## 开发者接口约定（代码调用）

  代码侧（如 query/indexer）仍通过 `providers.translation.create_translation_provider()` 获取实例并调用 `translate()`，但该实例现在固定是 **translator service client**，不再在业务侧做翻译 provider 选择。

  
  ### 输入输出形状（Shape）
  
  - `translate(text=...)` 支持：
    - **单条**：`text: str` → 返回 `Optional[str]`
    - **批量**：`text: List[str]` → 返回 `List[Optional[str]]`
  - **批量语义**：返回列表必须与输入 **等长且顺序对应**；某条翻译失败时，对应位置为 `None`（HTTP JSON 中表现为 `null`）。
  
  ### 批量能力标识（supports_batch）
  

  服务客户端与服务内后端都可以暴露 `supports_batch`。若后端不支持批量，服务端会逐条拆分并保持 shape。

  
  为便于上层（如 `api/translator_app.py`）做最优调用，provider 可暴露：
  
  - `supports_batch: bool`（property）