---
name: translation-assistant
description: 专业翻译助手，帮助配置翻译流程、优化翻译质量、管理术语表、排查翻译问题。触发条件：翻译相关任务、语言设置、Prompt定制、术语表管理、翻译质量优化、翻译问题排查。
---

# 翻译助手

## 快速开始

### 基本翻译命令
```bash
# 使用默认配置翻译
uv run ainiee translate input.txt -s Japanese -t Chinese -y

# PDF 文件翻译 (注意类型)
uv run ainiee translate input.pdf --type BabeldocPdf -y

# EPUB 文件翻译
uv run ainiee translate book.epub --type Epub -y

# 断点续传
uv run ainiee translate input.txt -r -y
```

## 配置指南

### 配置文件位置
```
Resource/profiles/
├── default.json    # 默认配置 (推荐修改这个)
└── {自定义}.json   # 可选：创建自己的配置
```

### 必须配置的字段

#### 1. API 平台配置
```json
{
  "platforms": {
    "deepseek": {
      "api_key": "sk-your-api-key",
      "api_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat",
      "auto_complete": true  // 关键！在线API必须为true
    }
  }
}
```

#### 2. 全局平台设置
```json
{
  "target_platform": "deepseek",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat",
  "api_settings": {
    "translate": "deepseek",
    "polish": "deepseek"
  }
}
```

#### 3. Prompt 选择配置 (必须!)
```json
{
  "translation_prompt_selection": {
    "last_selected_id": 100  // 整数! 不是字符串
  },
  "polishing_prompt_selection": {
    "last_selected_id": 10001  // 整数!
  }
}
```

### Prompt ID 对照表

| ID | 常量名 | 用途 |
|----|--------|------|
| 100 | COMMON | 通用翻译 |
| 200 | COT | Chain of Thought |
| 300 | THINK | 思考模式 |
| 1000 | CUSTOM | 自定义 |
| 10001 | POLISH_COMMON | 润色通用 |

### 语言设置

| 参数 | 可选值 |
|------|--------|
| `-s` 源语言 | `auto`, `Japanese`, `English`, `Korean`, `Chinese` |
| `-t` 目标语言 | `Chinese`, `TraditionalChinese`, `English`, `Japanese`, `Korean` |

### 文件类型

| 类型 | --type 参数 | 说明 |
|------|-------------|------|
| 文本 | `Txt` | 普通文本 |
| 电子书 | `Epub` | EPUB格式 |
| **PDF** | `BabeldocPdf` | **注意：不是 Pdf!** |
| 字幕 | `Srt`, `Ass`, `VTT`, `Lrc` | 字幕格式 |
| 文档 | `Docx`, `Md` | 办公文档 |
| 游戏 | `Renpy`, `Mtool`, `Trans`, `Tpp` | 游戏文本 |

## 翻译质量优化

### 1. 批处理参数
```bash
# 增加每批行数 (适合简单文本)
uv run ainiee translate input.txt --lines 30

# 减少每批行数 (适合复杂文本)
uv run ainiee translate input.txt --lines 10

# 增加上下文 (保持翻译一致性)
uv run ainiee translate input.txt --pre-lines 5
```

### 2. 模型参数 (Profile配置)
```json
{
  "temperature": 0.1,    // 低=更准确，高=更创造
  "top_p": 0.3,          // 采样阈值
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0
}
```

### 3. 不同平台的推荐配置

#### DeepSeek (推荐)
```json
{
  "deepseek": {
    "model": "deepseek-chat",
    "temperature": 1.3,
    "top_p": 1.0,
    "auto_complete": true
  }
}
```

#### OpenAI
```json
{
  "openai": {
    "model": "gpt-4o",
    "temperature": 0.3,
    "top_p": 1.0,
    "auto_complete": true
  }
}
```

#### 本地 SakuraLLM
```json
{
  "sakura": {
    "model": "Sakura-v1.0",
    "temperature": 0.1,
    "top_p": 0.3,
    "auto_complete": false
  }
}
```

## 问题排查

### 1. HTTP 404 错误

**症状**:
```
[ERROR] Request error (HARD_ERROR) [URL: https://api.xxx.com/v1, Model: xxx] ... HTTP 404
```

**原因**: `auto_complete` 未设置为 `true`

**解决**:
```json
{
  "platforms": {
    "deepseek": {
      "auto_complete": true  // 添加这个
    }
  }
}
```

### 2. KeyError: 'last_selected_id'

**症状**:
```
KeyError: 'last_selected_id'
```

**原因**: Prompt选择配置为空或格式错误

**解决**:
```json
{
  "translation_prompt_selection": {
    "last_selected_id": 100  // 必须是整数
  }
}
```

### 3. Unknown project type

**症状**:
```
Warning: Unknown translation project type 'Pdf'
No files loaded.
```

**原因**: 使用了错误的文件类型

**解决**:
```bash
# 错误
uv run ainiee translate input.pdf --type Pdf

# 正确
uv run ainiee translate input.pdf --type BabeldocPdf
```

### 4. API 连接测试

```bash
# 测试 DeepSeek
curl -s "https://api.deepseek.com/v1/models" \
  -H "Authorization: Bearer sk-xxx" | jq '.data[].id'

# 测试翻译请求
curl -s -X POST "https://api.deepseek.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hello"}]}'
```

### 5. 查看日志

```bash
# 查找最新日志
find . -name "*.log" -path "*AiNiee_Output*" -newer input.txt -exec cat {} \;

# 日志位置
{output_dir}/logs/session_*.log
```

## 高级功能

### 1. 双语输出
```json
{
  "enable_bilingual_output": true,
  "bilingual_text_order": "translation_first"
}
```

### 2. 简繁转换
```json
{
  "response_conversion_toggle": true,
  "opencc_preset": "s2twp.json"  // 简体→繁体(台湾)
}
```

可用预设:
- `s2twp.json` - 简体→台湾繁体
- `s2hk.json` - 简体→香港繁体
- `tw2s.json` - 台湾繁体→简体

### 3. 批量翻译

创建队列文件 `tasks.json`:
```json
{
  "tasks": [
    {
      "input_path": "novel1.txt",
      "profile": "lin",
      "source_lang": "Japanese",
      "target_lang": "Chinese"
    },
    {
      "input_path": "novel2.epub",
      "profile": "lin",
      "source_lang": "Japanese",
      "target_lang": "Chinese"
    }
  ]
}
```

执行:
```bash
uv run ainiee queue --queue-file tasks.json
```

### 4. 思考模式 (DeepSeek-Reasoner)
```bash
# 使用推理模型
uv run ainiee translate input.txt --model deepseek-reasoner

# 或在 profile 中配置
{
  "deepseek": {
    "model": "deepseek-reasoner",
    "think_switch": true
  }
}
```

## 完整配置模板

```json
{
  "platforms": {
    "deepseek": {
      "tag": "deepseek",
      "api_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key",
      "model": "deepseek-chat",
      "temperature": 1.3,
      "top_p": 1.0,
      "auto_complete": true,
      "rpm_limit": 4096,
      "tpm_limit": 10000000
    }
  },
  "target_platform": "deepseek",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat",
  "source_language": "Japanese",
  "target_language": "Chinese",
  "api_settings": {
    "translate": "deepseek",
    "polish": "deepseek"
  },
  "translation_prompt_selection": {
    "last_selected_id": 100
  },
  "polishing_prompt_selection": {
    "last_selected_id": 10001
  },
  "lines_limit": 20,
  "pre_line_counts": 3,
  "retry_count": 3,
  "round_limit": 3,
  "request_timeout": 60,
  "response_check_switch": {
    "newline_character_count_check": true,
    "return_to_original_text_check": true,
    "residual_original_text_check": true,
    "reply_format_check": true
  },
  "response_conversion_toggle": true,
  "opencc_preset": "s2twp.json"
}
```

## 常用命令速查

```bash
# 日文小说翻译
uv run ainiee translate novel.txt -s Japanese -t Chinese -y

# 英文文档翻译
uv run ainiee translate doc.txt -s English -t Chinese -y

# PDF 翻译
uv run ainiee translate doc.pdf --type BabeldocPdf -y

# EPUB 翻译
uv run ainiee translate book.epub --type Epub -y

# 断点续传
uv run ainiee translate novel.txt -r -y

# 测试配置
uv run ainiee translate test.txt --lines 1 -y
```
