# DeepL 翻译优化指南

## 问题描述

在电商搜索环境中，DeepL 翻译可能会遇到多义词翻译不准确的问题。例如：
- "车" 被翻译为 "rook"（象棋中的车）而不是 "car"（汽车）

## 解决方案

我们实现了以下优化方案来改善 DeepL 在电商场景下的翻译准确性：

### 1. 上下文提示（Context Hints）

系统会自动为单字查询添加电商上下文，帮助 DeepL 理解查询的领域。

**工作原理：**
- 对于中文单字查询（如 "车"），系统会自动添加上下文 "购买 车"
- DeepL 会根据上下文将 "车" 翻译为 "car" 而不是 "rook"
- 翻译完成后，系统会自动提取实际的查询词（"car"）

**配置：**
在 `config/config.yaml` 中可以设置翻译上下文：

```yaml
query_config:
  translation_context: "e-commerce product search"  # 默认值
```

### 2. 术语表（Glossary）支持（推荐方案）

DeepL 支持使用自定义术语表来确保特定词汇的准确翻译。这是解决多义词问题的最佳方案。

#### 创建术语表

1. **使用 DeepL API 创建术语表：**

```python
import requests

# 创建术语表
api_url = "https://api.deepl.com/v2/glossaries"
headers = {
    "Authorization": "DeepL-Auth-Key YOUR_API_KEY",
    "Content-Type": "application/json",
}

# 术语表内容（TSV 格式）
glossary_entries = """车\tcar
手机\tmobile phone
电脑\tcomputer"""

payload = {
    "name": "e-commerce-glossary",
    "source_lang": "ZH",
    "target_lang": "EN",
    "entries": glossary_entries,
    "entries_format": "tsv"
}

response = requests.post(api_url, headers=headers, json=payload)
if response.status_code == 201:
    glossary_id = response.json()["glossary_id"]
    print(f"术语表创建成功，ID: {glossary_id}")
```

2. **或者使用 DeepL 网页界面创建：**
   - 登录 DeepL Pro 账户
   - 进入术语表管理页面
   - 创建新的术语表，添加 "车" -> "car" 等映射

#### 配置术语表

在 `config/config.yaml` 中配置术语表 ID：

```yaml
query_config:
  translation_glossary_id: "your-glossary-id-here"  # DeepL 术语表 ID
```

#### 术语表格式

术语表使用 TSV（Tab-Separated Values）格式，每行一个词条：

```
车	car
手机	mobile phone
电脑	computer
```

**注意：**
- 术语表功能需要 DeepL Pro 账户（付费版）
- Free API 不支持术语表功能

### 3. 自动上下文处理

系统会自动检测以下情况并应用优化：

- **单字中文查询**：自动添加电商上下文
- **多字查询**：DeepL 通常有足够的上下文，无需特殊处理
- **非中文查询**：不应用上下文优化

## 使用示例

### 示例 1：使用上下文提示（自动）

查询 "车" 时：
1. 系统检测到这是单字中文查询
2. 自动添加上下文："购买 车"
3. DeepL 翻译为 "buy car"
4. 系统提取实际查询词："car"

### 示例 2：使用术语表（推荐）

1. 创建术语表，包含 "车" -> "car" 的映射
2. 在配置中设置 `translation_glossary_id`
3. 查询 "车" 时，DeepL 直接使用术语表翻译为 "car"

## 最佳实践

1. **优先使用术语表**：
   - 对于常见的电商术语，创建术语表是最可靠的方案
   - 术语表可以确保翻译的一致性和准确性

2. **上下文提示作为补充**：
   - 对于未在术语表中的词汇，上下文提示可以提供帮助
   - 系统已默认启用，无需额外配置

3. **定期更新术语表**：
   - 根据实际使用情况，不断添加新的术语映射
   - 特别是品牌名、产品类别等专业术语

## 技术实现细节

### 上下文添加逻辑

```python
# 对于单字查询（长度 <= 2 个字符）
if len(text.strip().split()) == 1 and len(text.strip()) <= 2:
    context_phrase = f"购买 {text}"  # 添加 "购买" 前缀
    return context_phrase, True  # 需要从结果中提取
```

### 结果提取逻辑

翻译结果 "buy car" 会被处理：
1. 识别上下文词（buy, purchase, product 等）
2. 提取非上下文词作为实际查询词
3. 返回 "car"

## 常见问题

### Q: 为什么 "车" 会被翻译为 "rook"？

A: DeepL 在处理单字查询时，缺乏上下文来判断词义。"车" 在中文中既可以指汽车，也可以指象棋中的车。通过添加电商上下文或使用术语表，可以解决这个问题。

### Q: 术语表和上下文提示哪个更好？

A: 术语表是更可靠的方案，因为它直接指定了翻译映射。上下文提示是自动的补充方案，适用于未在术语表中的词汇。

### Q: Free API 可以使用术语表吗？

A: 不可以。术语表功能需要 DeepL Pro（付费版）账户。Free API 只能使用上下文提示优化。

### Q: 如何测试翻译效果？

A: 可以通过搜索 API 测试翻译结果，查看返回的 `translations` 字段：

```bash
curl -X POST http://localhost:6002/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "车", "tenant_id": "test"}'
```

## 相关文件

- `query/translator.py` - 翻译器实现
- `query/query_parser.py` - 查询解析器（调用翻译器）
- `config/config.yaml` - 配置文件
- `config/config_loader.py` - 配置加载器

## 参考资源

- [DeepL API 文档](https://www.deepl.com/docs-api)
- [DeepL 术语表功能](https://www.deepl.com/docs-api/managing-glossaries/)