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

# 翻译助手

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

## 安装

### 前置条件：安装 uv

**重要**：aitf 需要 `uv` 作为包管理器。如果系统没有安装 uv，请先安装。

#### 自动检测并安装 uv

```bash
# 检测 uv 是否已安装，未安装则自动安装
if ! command -v uv &>/dev/null/null; then
    echo "uv 未安装，正在自动安装..."

    # macOS/Linux 官方安装脚本（推荐）
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # 安装后重新加载 shell 环境
    source ~/.bashrc 2>/dev/null || source ~/.zshrc 2>/dev/null || true
fi

# 验证安装
uv --version
```

#### 手动安装 uv

**macOS / Linux:**
```bash
# 官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 Homebrew (macOS)
brew install uv
```

**Windows:**
```powershell
# PowerShell（推荐）
irm https://astral.sh/uv/install.ps1 | iex

# 或使用 Scoop
scoop install uv

# 或使用 Chocolatey
choco install uv
```

#### 验证 uv 安装

```bash
# 检查版本
uv --version

# 预期输出示例：uv 0.5.x
```

### 方式一：uv tool install（推荐）

```bash
# 全局安装（首次安装）
uv tool install aitf

# 强制安装最新版本（已安装过时）
uv tool install --force aitf

# 或升级到最新版本
uv tool install -U aitf

# 或重新安装
uv tool install --reinstall aitf

# 验证安装
uv pip show aitf | grep Version
```

## 快速开始

```bash
# 完整参数翻译（推荐）
aitf translate "/path/to/file.pdf" \
  -y \
  --profile "default" \
  --rules-profile "default" \
  -s "English" \
  -t "Chinese" \
  --platform "deepseek"

# 简单翻译（使用默认配置）
aitf translate input.txt -s Japanese -t Chinese -y
```

## 执行流程

当用户请求翻译时，按以下步骤执行：

1. **检查文件存在性**：确认文件路径有效
2. **检查 uv 安装**：运行 `which uv && uv --version`
3. **检查 aitf 安装**：运行 `uv tool list | grep aitf`，如未安装则先安装
4. **执行翻译**：使用 `aitf translate` 命令

## 常用参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `-p, --profile` | 指定配置文件 | `-p default` |
| `--rules-profile` | 指定规则配置文件 | `--rules-profile default` |
| `-s` | 源语言 | `-s Japanese` |
| `-t` | 目标语言 | `-t Chinese` |
| `--platform` | API平台 | `--platform deepseek` |
| `-y` | 自动确认，无需交互 | `-y` |
| `-r` | 续接中断的翻译 | `-r` |
| `--lines` | 每批行数 | `--lines 20` |
| `--threads` | 线程数 | `--threads 4` |
| `--pre-lines` | 上下文行数 | `--pre-lines 3` |
| `--retry` | 重试次数 | `--retry 3` |
| `--timeout` | 超时秒数 | `--timeout 120` |
| `--think-depth` | 思考深度 | `--think-depth 1000` |

## 常见场景

### PDF 文件翻译（推荐完整参数）
```bash
aitf translate "/path/to/document.pdf" \
  -y \
  --profile "default" \
  --rules-profile "default" \
  -s "English" \
  -t "Chinese" \
  --platform "deepseek"
```

### 快速翻译（使用默认配置）
```bash
aitf translate file.txt -s Japanese -t Chinese -y
```

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

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

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

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

## 翻译结果

翻译完成后，结果保存在 `<原文件名>_AiNiee_Output/` 目录中。

**输出报告示例**：
```
✓ 任务执行总结报告
│   总翻译行数:      128
│   总消耗 Token:    11844
│   总持续时间:      20.0s
```

## 支持的文件格式

Txt, Epub, Srt, Ass, VTT, Lrc, Renpy, Mtool, Docx, Md, **Pdf**, 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

## 故障排查

### uv 安装问题

#### 1. uv 命令未找到

**症状**：运行 `uv` 命令时提示 `command not found` 或 `uv: command not found`

**解决方案**：
```bash
# 方案 1：重新安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方案 2：重新加载 shell 环境
source ~/.bashrc 2>/dev/null || source ~/.zshrc 2>/dev/null || true

# 方案 3：检查 PATH 环境变量
echo $PATH | grep -o ".cargo/bin" || echo "需要添加 ~/.cargo/bin 到 PATH"

# 方案 4：手动添加到 PATH（临时）
export PATH="$HOME/.cargo/bin:$PATH"
```

#### 2. uv 安装后无法使用

**症状**：安装成功但命令仍不可用

**解决方案**：
```bash
# 检查安装位置
which uv || echo "uv 未找到"

# 如果在 ~/.cargo/bin/uv，则 ls -la ~/.cargo/bin/uv

# 添加到 PATH（永久，添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### 翻译诊断

遇到翻译问题时，首先运行小范围测试：

```bash
# 测试翻译（仅处理 1 行）
aitf translate input.txt --lines 1 -y
```

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

如果文件路径包含特殊字符（如撇号、中文、空格等）导致翻译失败，使用以下方法处理：

**方案 1：复制到简单路径（推荐）**
```bash
# 复制文件到 /tmp 并使用简单文件名
cp "/path/to/complex name's file.pdf" /tmp/simple_name.pdf

# 然后翻译
aitf translate /tmp/simple_name.pdf -y --profile "default" --rules-profile "default" -s "English" -t "Chinese" --platform "deepseek"
```

**方案 2：使用单引号包裹路径**
```bash
aitf translate '/path/to/file with spaces.pdf' -y
```

**常见特殊字符**：撇号 `'`、中文全角括号 `（）`、连续空格、Unicode 字符

## 配置优化

详见 `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。
