翻译模块

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

环境变量

# Qwen（默认）
DASHSCOPE_API_KEY=sk-xxx

# DeepL
DEEPL_AUTH_KEY=xxx

# 可选
TRANSLATION_MODEL=qwen  # 或 deepl

重要限速说明（Qwen 机翻）
当前默认的 Qwen 翻译后端使用 qwen-mt-flash 云端模型，官方限速较低，约 RPM=60（每分钟约 60 请求）。

• 推荐通过 Redis 翻译缓存复用结果，避免对相同文本重复打云端
  
• 高并发场景需要在调用端做限流 / 去抖，或改为离线批量翻译
  
• 如需更高吞吐，可考虑 DeepL 或自建翻译服务

Provider 配置

Provider 与 URL 在 config/config.yaml 的 services.translation。详见 QUICKSTART.md §3 与 DEVELOPER_GUIDE.md §7.2。

HTTP 接口契约（translator service，端口 6006）

服务默认监听 http://localhost:6006，提供：

• POST /translate: 文本翻译（支持 qwen/qwen-mt、deepl、llm）
• GET /health: 健康检查

POST /translate

请求体：

{
  "text": "商品名称",
  "target_lang": "en",
  "source_lang": "zh",
  "model": "qwen",
  "context": "sku_name",
  "prompt": null
}

• text 支持两种形式：
  • 单条：string
  • 批量：string[]（等长返回，顺序对应）

响应体（单条）：

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

响应体（批量）：

{
  "text": ["商品名称1", "商品名称2"],
  "target_lang": "en",
  "source_lang": "zh",
  "translated_text": ["Product name 1", null],
  "status": "success",
  "model": "qwen"
}

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

---

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

除 HTTP 微服务外，代码侧（如 query/indexer）通常通过 providers.translation.create_translation_provider() 获取翻译 provider 实例并调用 translate()。

输入输出形状（Shape）

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

批量能力标识（supports_batch）

不同 provider 对批量的实现方式可能不同（例如：真正一次请求传多条，或内部循环逐条翻译并保持 shape）。

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

• supports_batch: bool（property）

上层在收到 text 为列表时：

• 若 supports_batch=True：可以直接将列表传给 translate(text=[...])
• 若 supports_batch=False：上层会逐条拆分调用（仍保证输出列表一一对应、失败为 null）