# 詞庫操作指南

## 詞庫結構

```
src/zhtw/data/terms/
├── cn/              # 簡體 → 台灣
│   ├── base.json    # 基礎詞彙
│   ├── it.json      # IT 術語
│   └── business.json
├── hk/              # 港式 → 台灣
│   ├── base.json
│   └── tech.json
└── pending/         # 待審核
```

---

## 詞庫格式

```json
{
  "version": "1.0",
  "description": "說明文字",
  "terms": {
    "简体词": "繁體詞",
    "软件": "軟體"
  }
}
```

---

## 新增詞彙流程

### 1. 確認正確性

```
問自己：
- 這個詞在台灣確實「不使用」嗎？
- 轉換後的詞在台灣「常用」嗎？
- 有沒有可能誤轉其他正確用語？
```

### 2. 檢查子字串問題

```
如果新詞是其他詞的一部分，需要加 identity mapping：

例：要加 "算法" → "演算法"
問：有沒有包含 "算法" 的台灣正確詞？
答：有，"演算法" 本身就是正確的
解：同時加入 "演算法" → "演算法"
```

### 3. 編輯詞庫

```bash
# 找到對應的詞庫檔案
vim src/zhtw/data/terms/cn/base.json

# 加入新詞
{
  "terms": {
    "existing": "existing_translation",
    "新词": "新詞"
  }
}
```

### 4. 驗證

```bash
# 檢查詞庫衝突
python -m zhtw validate

# 執行測試
pytest tests/test_dictionary.py -v
```

---

## Identity Mapping 機制

### 原理

當詞庫包含 `"演算法": "演算法"` 時，Matcher 會：
1. 標記 "演算法" 為「保護區」
2. 保護區內的子字串不會被轉換
3. 所以 "算法" 不會在 "演算法" 內部被匹配

### 何時需要

```
✅ 需要 identity mapping：
- "演算法" 包含 "算法" → 加 "演算法": "演算法"
- "表情符號" 包含 "表情" → 加 "表情符號": "表情符號"
- "中文檔案" 包含 "文檔" → 加 "檔案": "檔案"

❌ 不需要：
- 獨立的詞，不會造成子字串誤判
```

### 檢查方法

```python
from zhtw.matcher import Matcher

# 測試是否有誤判
m = Matcher({"算法": "演算法"})
matches = m.find_matches("演算法")
print(matches)  # 應該為空或只有 identity

# 如果有誤判，加入 identity mapping
m = Matcher({
    "算法": "演算法",
    "演算法": "演算法"  # 保護
})
```

---

## 常見陷阱

| 錯誤 | 問題 | 解決 |
|------|------|------|
| `"表情" → "表情符號"` | 「臉部表情」變成「臉部表情符號」 | 改用更精確的詞 |
| `"橙" → "柳橙"` | 「橙色」變成「柳橙色」 | 用 "柳丁" → "柳橙" |
| `"程序" → "程式"` | 「程序員」正確但被拆開 | 加 "程序員" → "程式設計師" |

---

## 詞庫來源優先級

```
1. 自訂詞庫（--dict 指定）
2. 內建 cn/ 詞庫
3. 內建 hk/ 詞庫
```

自訂詞庫會覆蓋內建詞庫的相同 key。
