# 翻译模块

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

## 环境变量

```bash
# 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](./QUICKSTART.md) §3 与 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) §7.2。

## 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",
  "context": "sku_name",
  "prompt": null
}
```

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

**响应体**（单条）：

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

**响应体**（批量）：

```json
{
  "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`）