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

# 翻译助手

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

## 安装

### 方式一：uv tool install（推荐）
```bash
# 全局安装（首次安装）
uv tool install aitf

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

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

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

# 完整参数使用示例
aitf translate "/path/to/file.pdf" \
  -y \
  --profile "default" \
  --rules-profile "default" \
  -s "English" \
  -t "Chinese" \
  --platform "deepseek"
```

### 方式二：uvx（无需安装）
```bash
# 直接运行，自动下载（较慢）
uvx aitf translate "/path/to/file.pdf" \
  -y \
  --profile "default" \
  -s "English" \
  -t "Chinese" \
  --platform "deepseek"
```

### 方式三：uv run（项目开发）
```bash
# 在 aitf 项目目录下使用
cd /path/to/aitf-project
uv run aitf translate input.txt -y --profile default
```

## 快速开始

```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
```

## 常用参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `-p, --profile` | 指定配置文件 | `-p default` |
| `--rules-profile` | 指定规则配置文件 | `--rules-profile default` |
| `-s` | 源语言 | `-s Japanese` |
| `-t` | 目标语言 | `-t Chinese` |
| `--platform` | API平台 | `--platform deepseek` |
| `--type` | 文件类型(用于PDF等) | `--type BabeldocPdf` |
| `-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` |

## 常见场景

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

### 快速翻译
```bash
uv run aitf translate file.txt -s Japanese -t Chinese -y -p default
```

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

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

### 启动 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 -y --profile default --platform sakura
```

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

# 或使用通用 PDF 类型
uv run aitf translate "/path/to/document.pdf" \
  -y \
  --profile "default" \
  -s "English" \
  -t "Chinese" \
  --type Pdf
```

## 支持的文件格式

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 --profile default
```

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

**重要提示**：执行翻译前，**必须自动检测并处理**文件名中的特殊字符。

#### 自动处理流程（必须执行）

当用户请求翻译时，按以下流程处理：

1. **检测特殊字符**：
```python
import re

def has_special_chars(filename):
    """检测文件名是否包含特殊字符"""
    special_patterns = [
        r"['\"]",           # 撇号和引号
        r"[（）]",           # 中文括号
        r"\s{2,}",          # 多个连续空格
        r"[^\x00-\x7F]",    # 非ASCII字符
    ]
    return any(re.search(p, filename) for p in special_patterns)
```

2. **自动复制到简单路径**（如果检测到特殊字符）：
```bash
# 提取文件名中的关键词
basename="原始文件名.pdf"
keyword=$(echo "$basename" | sed 's/[^a-zA-Z0-9]//g' | head -c 10)

# 复制到 /tmp
cp "$original_path" /tmp/${keyword}_${RANDOM}.pdf
```

3. **使用简单路径执行翻译**

#### 完整自动处理示例

```bash
# 获取原始路径
ORIGINAL_PATH="/path/to/SAM'S CLUB file.pdf"

# 提取关键词（移除特殊字符）
KEYWORD=$(basename "$ORIGINAL_PATH" .pdf | sed 's/[^a-zA-Z0-9]//g' | head -c 10)

# 复制到简单路径
SIMPLE_PATH="/tmp/${KEYWORD}_$$"
cp "$ORIGINAL_PATH" "${SIMPLE_PATH}.pdf"

# 使用简单路径翻译
uv run aitf translate "${SIMPLE_PATH}.pdf" -y --profile "default" --rules-profile "default" -s "English" -t "Chinese" --platform "deepseek"
```

#### 常见特殊字符

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

#### 快速修复命令

当遇到特殊字符问题时，直接运行以下命令自动处理：

```bash
# 自动处理文件名并翻译
ORIGINAL_PATH="原始文件路径"  # 替换为实际路径
KEYWORD=$(basename "$ORIGINAL_PATH" .pdf 2>/dev/null | sed 's/[^a-zA-Z0-9]//g' | head -c 10)
SIMPLE_PATH="/tmp/${KEYWORD}_$$"
cp "$ORIGINAL_PATH" "${SIMPLE_PATH}.pdf" 2>/dev/null || cp "$ORIGINAL_PATH" "${SIMPLE_PATH}.pdf"
echo "简单路径: ${SIMPLE_PATH}.pdf"
```

然后使用输出的简单路径替换原始路径进行翻译。

**解决方案**：

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

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

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

**重要提示**：如果遇到文件路径问题，首先尝试将文件复制到 `/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。
