common/autoinstallers/rush-commands/src/convert-comments/implementation-plan.md
基于需求文档，本项目需要实现一个TypeScript脚本，用于将代码仓库内的中文备注自动转换为英文备注。
interface FileScanConfig {
root: string;
extensions: string[];
}
interface SourceFile {
path: string;
content: string;
language: 'typescript' | 'javascript' | 'go' | 'markdown' | 'other';
}
功能职责：
核心函数：
getGitTrackedFiles(root: string): Promise<string[]>filterFilesByExtensions(files: string[], extensions: string[]): string[]readSourceFiles(filePaths: string[]): Promise<SourceFile[]>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): booleaninterface TranslationConfig {
apiKey: string;
model: string;
maxRetries: number;
timeout: number;
}
interface TranslationResult {
original: string;
translated: string;
confidence: number;
}
功能职责：
核心函数：
translateComment(comment: string, context?: string): Promise<TranslationResult>batchTranslate(comments: string[]): Promise<TranslationResult[]>createTranslationPrompt(comment: string, language: string): stringinterface 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[]): stringinterface 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;
}
功能职责：
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>: 报告输出文件（可选）采用FP风格，主要体现在：
// 使用函数式风格的异步处理管道
const processRepository = pipe(
getGitTrackedFiles,
asyncMap(readFile),
asyncFilter(hasChineseComments),
asyncMap(extractChineseComments),
asyncMap(translateComments),
asyncMap(applyTranslations),
generateReport
);
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: 代码检查# 基本使用
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