---
name: translation-assistant
description: 使用 uv run aitf 或 uvx aitf 进行翻译配置、优化翻译质量，管理术语表、排查翻译问题。处理 AITF 项目的配置、翻译流程、文件格式支持、WebServer等问题。当用户提到翻译、翻译配置、翻译质量、术语表、翻译问题、排错、翻译助手、aitf、translate、polish、export 时触发此技能。
---

# 翻译助手

AITF 项目的综合翻译管理和维护技能。

## 运行方式

AITF 支持两种运行方式：

### 方式一：本地开发（推荐）
```bash
# 重要：需要使用 -p default 指定配置文件
uv run aitf translate input.txt -p default
```

### 方式二：已安装包
```bash
uvx aitf translate input.txt
```

## 快速开始

```bash
# 简单翻译（本地开发需要加 -p default）
uv run aitf translate input.txt -p default

# 指定配置翻译
uv run aitf translate input.txt -p lin -s Japanese -t Chinese

# 断点续传
uv run aitf translate input.txt -r -y -p default

# 使用 uvx（已安装包时）
uvx aitf translate input.txt -s Japanese -t Chinese -y
```

## 常用参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `-p` | 指定配置文件 | `-p lin` |
| `-s` | 源语言 | `-s Japanese` |
| `-t` | 目标语言 | `-t Chinese` |
| `--platform` | API平台 | `--platform sakura` |
| `--lines` | 每批行数 | `--lines 20` |
| `--threads` | 线程数 | `--threads 4` |
| `--pre-lines` | 上下文行数 | `--pre-lines 3` |
| `--retry` | 重试次数 | `--retry 3` |
| `--timeout` | 超时秒数 | `--timeout 120` |
| `--think-depth` | 思考深度 | `--think-depth 1000` |

## 常见场景

### 快速翻译
```bash
# 本地开发（重要：需要 -p default 指定配置）
uv run aitf translate file.txt -s Japanese -t Chinese -y -p default

# 已安装包
uvx aitf translate file.txt -s Japanese -t Chinese -y
```

### 续接中断的翻译
```bash
uv run aitf translate file.txt -r -y
```

### 润色已有翻译
```bash
uv run aitf polish file.txt -y
```

### 启动 WebServer
```bash
uv run aitf --web-mode
# 访问 http://127.0.0.1:8000
```

### 交互式配置
```bash
uv run aitf
# 选择菜单进行配置
# 2. Profile 管理 → 创建新 Profile
# 3. 设置 → 配置翻译参数
# 4. API 设置 → 选择平台
```

### 使用本地模型
```bash
uv run aitf translate file.txt --platform sakura
```

### PDF 文件翻译
```bash
# PDF 需要指定类型
uv run aitf translate /tmp/file.pdf --type BabeldocPdf -s English -t Chinese -y

# 或使用通用 PDF 类型
uv run aitf translate /tmp/file.pdf --type Pdf -s English -t Chinese -y
```

## 支持的文件格式

Txt, Epub, Srt, Ass, VTT, Lrc, Renpy, Mtool, Docx, Md, **Pdf (需要 --type BabeldocPdf)**, I18next, Po, Csv, Vnt, Paratranz

## 支持的语言

**源语言**: auto, Japanese, English, Korean, Chinese
**目标语言**: Chinese, TraditionalChinese, English, Japanese, Korean

## 支持的API平台

**本地**: sakura, murasaki, LocalLLM
**在线**: openai, deepseek, anthropic, google, zhipu, moonshot, siliconflow, dashscope

## 故障排查

遇到问题时，首先运行诊断：

```bash
uv run aitf translate input.txt --lines 1 -y
```

### 文件路径特殊字符问题

**问题表现**：文件读取失败，提示 "File does not exist" 或 "No such file"

**常见特殊字符**：
- 撇号 `'` (如 `SAM'S CLUB`)
- 中文全角括号 `（）`
- 特殊空格字符
- Unicode 组合字符

**解决方案**：

1. **使用通配符复制到简单路径**（推荐）：
```bash
cd "/path/to/目录"
cp *关键词* /tmp/simple_name.pdf
uv run aitf translate /tmp/simple_name.pdf
```

2. **重命名源文件**（移除特殊字符）：
```bash
# macOS/Linux
mv "原名.pdf" "simple_name.pdf"
```

3. **使用 Tab 补全获取准确路径**：
```bash
# 输入部分文件名后按 Tab
uv run aitf translate ./part[TAB]
```

**重要提示**：如果遇到文件路径问题，首先尝试将文件复制到 `/tmp/` 目录并使用简单的英文文件名。

查看 `references/troubleshooting.md` 获取详细的故障排查流程。

## 配置优化

详见 `references/configuration.md`:
- 翻译参数优化
- API 参数配置
- 响应检查设置

## 翻译质量

详见 `references/quality-optimization.md`:
- 批处理参数调整
- 模型参数配置
- 思考模式使用
- 术语表管理

## 项目开发

详见 `references/development.md`:
- 代码结构说明
- 插件开发指南
- 文件格式扩展
- WebServer 开发

## 核心模块

- **TextProcessor**: 文本规范化、占位符处理
- **PromptBuilder**: Prompt 模板构建
- **LLMRequester**: API 请求处理
- **ResponseExtractor**: 响应解析
- **ResponseChecker**: 质量验证

详见 `references/translation-workflow.md`。

## Agents

本 skill 包含以下专用 agents:

- **诊断 agent**: `agents/diagnostics.md` - 自动诊断翻译问题
- **配置 agent**: `agents/configurator.md` - 帮助配置优化

当需要深度分析或自动排查问题时，使用这些 agents。
