# ai-translator

**Repository Path**: yihui/ai-translator

## Basic Information

- **Project Name**: ai-translator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多 AI 协同翻译工作台

纯前端应用：上传 PDF / DOCX / TXT 文件，按段落拆分展示，然后逐段由多位不同风格的 AI 译员协同翻译、交叉评分，选出最优译文。全流程实时可视，支持多轮迭代与多格式导出。全流程在浏览器端运行，无需后端。

基于 **React 18 + TypeScript + Vite + Zustand + Tailwind CSS** 构建。

## 功能特性

- 📄 **文件解析与智能段落拆分**
  - 支持 PDF（pdf.js）、DOCX（mammoth）、TXT
  - 上传后自动解析并按段落拆分，过长段落按标点再切分
  - **相邻短段落自动合并**：小于 140 字的相邻短段落自动合并，合并后不超过 280 字，减少 API 调用、保留更完整的上下文
  - 解析完成后可预览所有段落，确认后开始翻译

- 🤖 **多 AI 协同翻译**
  - 默认 3 位译员，各有独立风格提示词、模型与 API 配置
  - 支持中→英、英→中、自动检测方向
  - 批量评分：每位译员一次调用评分所有候选译文，减少 API 调用
  - **译员配置弹框**：在弹框中统一管理 Base URL / API Key / 模型名称 / 风格，支持添加和删除译员，主界面简洁不暴露密钥

- ⚖️ **交叉评分与最高分决议**
  - 每位译员为所有候选打分（0–10）并给出**扣分原因**和**修改建议**
  - **评分制选择**：直接选取平均分最高且 ≥ 阈值的候选作为最终译文，不再使用投票
  - 未通过则进入下一轮改进，最多可配置轮数

- 🔁 **多轮迭代与完整上下文累积**
  - 第二轮起，译员会收到上一轮的**完整反馈**：每个候选的译文、各位审校员的评分、扣分原因、修改建议
  - 多轮反馈累积传递，帮助译员避免重复之前的问题

- 🎯 **实时可视化流水线**
  - 上传 → 解析 → 确认段落列表 → 逐段自动翻译
  - 每个段落独立显示进度：当前轮次、候选译文、评分、扣分原因、修改建议
  - 可展开查看每轮详细评分与反馈

- 📊 **多模式结果导出**
  - **导出原文+译文**：Markdown 格式，包含每段原文与最终译文
  - **仅导出译文**：纯文本格式，只保留最终译文，便于直接使用

## 技术架构

```
React 18 + TypeScript
├── Vite            构建工具，开发服务器
├── Zustand         状态管理（workspace-store）
├── Tailwind CSS    样式
└── 浏览器直连 AI API（无需后端）
```

### 核心流程

```
上传文件 → 解析段落 → 短段落合并 → 确认段落列表 → 逐段翻译流水线
                                                    │
                                                    ▼
                                          ┌─── 第 1 轮 ───┐
                                          │ 译员A → 候选A  │
                                          │ 译员B → 候选B  │  并行翻译
                                          │ 译员C → 候选C  │
                                          └───────┬───────┘
                                                  ▼
                                  批量评分（每位译员一次调用评所有候选）
                                  输出：分数 + 扣分原因 + 修改建议
                                                  ▼
                                          最高分决议
                                            │            │
                                  最高分 ≥ 阈值     最高分 < 阈值
                                            │            │
                                          采纳      累积完整上下文 → 下一轮
```

## 项目结构

```
src/
├── components/
│   ├── config-panel/
│   │   ├── ConfigPanel.tsx          左侧配置面板（简化版）
│   │   └── TranslatorDialog.tsx     译员配置弹框（Base URL/Key/模型/增删）
│   └── workspace/
│       ├── ParagraphCard.tsx        段落卡片（生命周期、评分、扣分原因展示）
│       └── WorkspacePanel.tsx       主工作区（含双模式导出）
├── engine/
│   ├── adapters/
│   │   ├── types.ts                 AI 适配器接口
│   │   └── deepseek-adapter.ts      DeepSeek API 适配器
│   ├── lang-detect.ts               中/英语言检测
│   ├── translator.ts                CollaborativeTranslator 核心
│   └── voting.ts                    评分聚合、最高分决议、上下文构建
├── parsers/
│   ├── file-parser.ts               文件解析（TXT/PDF/DOCX）
│   └── paragraph-splitter.ts        段落拆分 + 短段落合并
├── pipeline/
│   └── pipeline-controller.ts       翻译流水线控制器
├── store/
│   └── workspace-store.ts           Zustand 全局状态
├── styles/
│   └── globals.css                  Tailwind + 全局样式
├── types/
│   └── index.ts                     全局 TypeScript 类型
├── App.tsx                          应用根组件
├── main.tsx                         入口
└── vite-env.d.ts                    Vite 环境类型声明
```

## 快速开始

### 环境要求

- Node.js ≥ 18
- npm 或 pnpm

### 安装

```bash
npm install
```

### 配置 API Key

复制环境变量模板并填入你的 DeepSeek API Key：

```bash
cp .env.example .env
```

编辑 `.env`：

```
VITE_DEEPSEEK_API_KEY=your-api-key-here
VITE_DEEPSEEK_BASE_URL=https://api.deepseek.com
```

> 也可在应用运行后，点击左侧"配置译员"按钮，在弹框中为每位译员单独配置 Base URL / API Key / 模型。

### 开发

```bash
npm run dev
```

访问 http://localhost:8765

### 构建

```bash
npm run build
npm run preview
```

## 配置说明

应用内置 3 位译员，使用 DeepSeek API 的不同模型和提示词风格：

| 译员 | 模型 | 风格 |
|------|------|------|
| Alpha（直译严谨） | deepseek-chat | 忠实原文结构与术语 |
| Beta（流畅自然） | deepseek-v4-flash | 以目标语言读者流畅度为优先 |
| Gamma（简洁干练） | deepseek-v4-pro | 保持信息完整，用最简洁的表达 |

左侧配置面板可自定义：
- 翻译方向（中→英 / 英→中 / 自动）
- 最大轮数、评分阈值
- 翻译背景 / 领域说明
- 参考翻译
- 译员启用/禁用

点击 **"配置译员"** 按钮打开弹框，可：
- 编辑每位译员的名称、Base URL、API Key、模型名称、风格描述
- 添加新译员或删除已有译员
- 切换译员启用状态

## 数据流

### 翻译阶段

每位译员收到：
- 源文本、源语言、目标语言
- 译员风格提示词
- 翻译背景 / 参考翻译
- **上一轮完整反馈**（第 2 轮起）：包含每个候选的译文、各位审校员的评分、扣分原因、修改建议

### 评分阶段（批量）

每位译员一次调用评分**所有候选译文**，收到：
- 源文本
- 所有候选译文列表
- 评分员角色描述
- 返回每个候选的：
  - 分数（0–10）
  - **扣分原因**（具体说明扣分点）
  - **修改建议**（具体改进方法）

### 决议阶段

- 计算每个候选的平均分
- **选取平均分最高的候选**
- 通过条件：**最高平均分 ≥ 评分阈值**（默认 9）
- 纯本地计算，无 API 调用
- 未通过则累积完整上下文进入下一轮

### 段落合并策略

解析后的段落会经过短段落合并处理：
- **合并条件**：当前段与下一段都 < 140 字，且合并后 ≤ 280 字
- **效果**：减少段落数量、降低 API 调用次数、保留更完整的上下文，提升翻译质量与效率

## 测试

项目包含 Playwright E2E 测试（Python）：

```bash
# 完整翻译流程测试（解析 → 翻译 → 评分 → 导出验证）
python test_e2e.py
```

测试覆盖：
- 文件解析与短段落合并
- 多轮翻译流程完整性
- 评分阈值通过条件（平均分 ≥ 9）
- UI 元素（扣分原因、修改建议、导出按钮）

## 许可

MIT