# 翻譯 Agent (Translation Agent) 設計文件

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |
| 用途 | 提供多語言文本翻譯服務 (應用於 Portal Chunk Detail) |

---

## 1. Agent 概覽

Translation Agent 負責將系統中的非結構化文本（如 Chunk 內容、摘要、5W1H 推論結果）翻譯為使用者指定的語言。
在 Portal 的 **Chunk Search Detail** 頁面，當使用者瀏覽不同語言的影片內容時，此 Agent 提供即時翻譯支援。

### 1.1 資源註冊資訊 (Resource Registry)

當 Agent 啟動時，將向 **Resource Registry** 註冊以下資訊：

```json
{
  "resource_id": "agent_text_translation_v1",
  "resource_type": "agent",
  "capabilities": ["translate_text", "detect_language", "batch_translate"],
  "category": "text_processing",
  "config": {
    "default_model": "gpt-4o-mini",
    "fallback_model": "local-llama-3-8b",
    "max_tokens": 4096,
    "supported_languages": ["zh-TW", "en-US", "ja-JP", "ko-KR"]
  }
}
```

---

## 2. 核心設計

### 2.1 輸入格式 (Input)

Agent 接收來自 Portal 或內部 API 的 JSON 請求：

```json
{
  "text": "He walked into the room and saw a large red car.",
  "target_language": "zh-TW",
  "source_language": "auto", 
  "context": {
    "domain": "movie_subtitle",
    "glossary": {
      "red car": "紅色跑車" 
    }
  }
}
```

- `text`: 待翻譯文本。
- `target_language`: 目標語言 (BCP 47 格式)。
- `context` (可選): 提供領域資訊或專有名詞對照表 (Glossary) 以提高準確度。

### 2.2 輸出格式 (Output)

Agent 回傳標準化 JSON：

```json
{
  "translated_text": "他走進房間，看到一輛紅色跑車。",
  "source_language_detected": "en-US",
  "confidence": 0.98,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}
```

---

## 3. Prompt 設計 (System Prompt)

為了確保翻譯風格符合 Momentry Core 的專業性（如準確的影視術語），我們使用以下 System Prompt：

```text
You are a professional translator for Momentry Core, a digital asset management system specializing in video analysis.

## Guidelines:
1. **Accuracy**: Translate the meaning accurately, maintaining the original tone.
2. **Context Awareness**: If a glossary is provided in the context, strictly follow it.
3. **Style**: 
   - For subtitles: Keep it concise and natural for reading.
   - For technical terms (e.g., 5W1H, metadata): Use standard industry translations.
4. **Format**: Preserve any JSON structure, markdown, or timestamps present in the input text. Do not translate code blocks.
5. **Output**: Return ONLY the translated text in the requested format unless asked otherwise.
```

---

## 4. API 端點設計

### 4.1 單一翻譯

```http
POST /api/v1/agents/translate
Content-Type: application/json
X-Resource-Id: agent_text_translation_v1

{
  "text": "...",
  "target_language": "zh-TW"
}
```

### 4.2 批次翻譯 (Batch Translation)

針對 Chunk Detail 頁面可能一次顯示多個段落，支援批次翻譯：

```http
POST /api/v1/agents/translate/batch
Content-Type: application/json

{
  "items": [
    { "id": "chunk_001", "text": "..." },
    { "id": "chunk_002", "text": "..." }
  ],
  "target_language": "zh-TW"
}
```

---

## 5. 錯誤處理與容錯

- **模型降級 (Fallback)**: 若 `gpt-4o-mini` 超時或不可用，自動切換至本地模型 `local-llama-3-8b`。
- **Token 超長**: 若文本超過 `max_tokens`，自動進行分段翻譯 (Split & Translate)。
- **無效語言**: 若 `target_language` 不在支援列表中，回傳 `400 Bad Request`。

---

## 6. Portal 整合範例 (Chunk Detail)

在 Portal 的 `ChunkDetailView.vue` 中，翻譯功能的調用流程如下：

1. 使用者點擊「翻譯為 繁體中文」按鈕。
2. Portal 發送 POST 請求至 `/api/v1/agents/translate`。
3. 取得結果後，在不重新整理頁面的情況下更新 UI (顯示 `translated_text`)。

```typescript
// Portal 前端調用範例
async function translateChunkText(text: string, targetLang: string) {
  const response = await fetch('/api/v1/agents/translate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text, target_language: targetLang })
  });
  return response.json();
}
```

---

## 版本資訊

- 版本: V1.0
- 建立日期: 2026-04-25
