# 中文备注转换为英文 - 实现方案

## 项目概述

基于需求文档，本项目需要实现一个TypeScript脚本，用于将代码仓库内的中文备注自动转换为英文备注。

## 核心模块设计

### 1. 文件扫描模块 (FileScanModule)

```typescript
interface FileScanConfig {
  root: string;
  extensions: string[];
}

interface SourceFile {
  path: string;
  content: string;
  language: 'typescript' | 'javascript' | 'go' | 'markdown' | 'other';
}
```

**功能职责：**
- 调用git命令获取仓库所有源码文件
- 根据文件扩展名过滤目标文件
- 读取文件内容并识别编程语言类型

**核心函数：**
- `getGitTrackedFiles(root: string): Promise<string[]>`
- `filterFilesByExtensions(files: string[], extensions: string[]): string[]`
- `readSourceFiles(filePaths: string[]): Promise<SourceFile[]>`

### 2. 中文检测模块 (ChineseDetectionModule)

```typescript
interface ChineseComment {
  content: string;
  startLine: number;
  endLine: number;
  startColumn: number;
  endColumn: number;
  type: 'single-line' | 'multi-line' | 'documentation';
}

interface FileWithComments {
  file: SourceFile;
  chineseComments: ChineseComment[];
}
```

**功能职责：**
- 解析不同语言的注释语法
- 识别包含中文字符的注释
- 提取注释的精确位置信息

**核心函数：**
- `detectChineseInComments(file: SourceFile): ChineseComment[]`
- `parseCommentsByLanguage(content: string, language: string): Comment[]`
- `containsChinese(text: string): boolean`

### 3. 翻译服务模块 (TranslationModule)

```typescript
interface TranslationConfig {
  apiKey: string;
  model: string;
  maxRetries: number;
  timeout: number;
}

interface TranslationResult {
  original: string;
  translated: string;
  confidence: number;
}
```

**功能职责：**
- 调用OpenAI API进行翻译
- 处理翻译错误和重试
- 保持代码注释的格式和结构

**核心函数：**
- `translateComment(comment: string, context?: string): Promise<TranslationResult>`
- `batchTranslate(comments: string[]): Promise<TranslationResult[]>`
- `createTranslationPrompt(comment: string, language: string): string`

### 4. 文件替换模块 (FileReplacementModule)

```typescript
interface ReplacementOperation {
  file: string;
  replacements: Array<{
    start: number;
    end: number;
    original: string;
    replacement: string;
  }>;
}
```

**功能职责：**
- 精确替换文件中的中文注释
- 保持代码格式和缩进
- 创建备份机制

**核心函数：**
- `replaceCommentsInFile(file: SourceFile, replacements: ReplacementOperation): Promise<void>`
- `createBackup(filePath: string): Promise<string>`
- `applyReplacements(content: string, replacements: Replacement[]): string`

### 5. 报告生成模块 (ReportModule)

```typescript
interface ProcessingReport {
  totalFiles: number;
  processedFiles: number;
  translatedComments: number;
  errors: Error[];
  duration: number;
  details: FileProcessingDetail[];
}

interface FileProcessingDetail {
  file: string;
  commentCount: number;
  status: 'success' | 'error' | 'skipped';
  errorMessage?: string;
}
```

**功能职责：**
- 记录处理过程中的统计信息
- 生成详细的处理报告
- 记录错误和异常情况

## 命令行接口设计

### 主命令

```bash
ai-translate --root <directory> --exts <extensions> [options]
```

### 参数说明

- `--root, -r <directory>`: 需要处理的根目录（必填）
- `--exts, -e <extensions>`: 文件扩展名数组，如 "ts,js,go,md"（可选，默认处理所有文本文件）
- `--openai-key <key>`: OpenAI API密钥（可选，也可通过环境变量提供）
- `--model <model>`: OpenAI模型名称（可选，默认gpt-3.5-turbo）
- `--dry-run`: 仅分析不实际修改文件（可选）
- `--backup`: 创建文件备份（可选，默认启用）
- `--verbose, -v`: 详细输出模式（可选）
- `--output <file>`: 报告输出文件（可选）

## 技术实现细节

### 1. 函数式编程范式

采用FP风格，主要体现在：
- 纯函数设计：无副作用的数据转换
- 不可变数据结构：使用immutable.js或原生不可变操作
- 函数组合：通过pipe和compose构建处理流水线
- 错误处理：使用Either/Maybe模式处理异常

### 2. 异步处理策略

```typescript
// 使用函数式风格的异步处理管道
const processRepository = pipe(
  getGitTrackedFiles,
  asyncMap(readFile),
  asyncFilter(hasChineseComments),
  asyncMap(extractChineseComments),
  asyncMap(translateComments),
  asyncMap(applyTranslations),
  generateReport
);
```

### 3. 错误处理机制

- 使用Result类型封装成功/失败状态
- 实现重试机制处理网络错误
- 记录详细的错误日志和上下文
- 支持部分失败的情况下继续处理

### 4. 性能优化

- 并发处理：合理控制并发数量避免API限制
- 缓存机制：避免重复翻译相同内容
- 增量处理：仅处理修改过的文件
- 流式处理：大文件分块处理

## 项目结构

```
src/convert-comments/
├── index.ts                 # 主入口文件
├── cli/
│   ├── command.ts          # Commander.js命令定义
│   └── config.ts           # 配置管理
├── modules/
│   ├── file-scan.ts        # 文件扫描模块
│   ├── chinese-detection.ts # 中文检测模块
│   ├── translation.ts      # 翻译服务模块
│   ├── file-replacement.ts # 文件替换模块
│   └── report.ts          # 报告生成模块
├── utils/
│   ├── git.ts             # Git操作工具
│   ├── language.ts        # 编程语言识别
│   ├── chinese.ts         # 中文字符检测
│   └── fp.ts             # 函数式编程工具
├── types/
│   ├── index.ts           # 类型定义
│   └── config.ts          # 配置类型
└── __tests__/
    ├── unit/              # 单元测试
    └── integration/       # 集成测试
```

## 依赖包选择

### 核心依赖
- `commander`: 命令行接口
- `openai`: OpenAI API客户端
- `simple-git`: Git操作
- `ramda` 或 `lodash/fp`: 函数式编程工具

### 开发依赖
- `typescript`: TypeScript编译器
- `@types/node`: Node.js类型定义
- `jest`: 测试框架
- `prettier`: 代码格式化
- `eslint`: 代码检查

## 开发阶段规划

### 阶段1：基础框架搭建
1. 项目初始化和依赖安装
2. TypeScript配置和构建脚本
3. 命令行接口框架
4. 基础类型定义

### 阶段2：核心功能实现
1. 文件扫描模块
2. 中文检测模块
3. 翻译服务模块
4. 文件替换模块

### 阶段3：完善和优化
1. 报告生成模块
2. 错误处理和重试机制
3. 性能优化
4. 单元测试和集成测试

### 阶段4：发布准备
1. 文档完善
2. 使用示例
3. 打包和发布脚本
4. CI/CD配置

## 使用示例

```bash
# 基本使用
ai-translate --root ./src --exts ts,js,go

# 仅分析不修改
ai-translate --root ./src --dry-run

# 指定OpenAI配置
ai-translate --root ./src --openai-key sk-... --model gpt-4

# 生成详细报告
ai-translate --root ./src --verbose --output report.json
```

## 质量保证

### 测试策略
- 单元测试：覆盖所有核心函数
- 集成测试：端到端流程验证
- 性能测试：大型仓库处理能力
- 安全测试：API密钥保护

### 代码质量
- TypeScript严格模式
- ESLint规则检查
- Prettier代码格式化
- 代码覆盖率要求>90%

## 风险和缓解措施

### 主要风险
1. **API配额限制**：OpenAI API调用频率限制
2. **翻译质量**：自动翻译可能不够准确
3. **文件损坏**：替换操作可能破坏文件
4. **性能问题**：大型仓库处理时间过长

### 缓解措施
1. 实现智能重试和降级机制
2. 提供人工审核和修正功能
3. 强制备份和回滚机制
4. 并发控制和进度显示