coze-studio/common/autoinstallers/rush-commands/src/convert-comments/README.md

中文备注转换为英文 - 项目概览

📖 项目简介

本项目是一个TypeScript命令行工具，用于自动将代码仓库中的中文注释翻译为英文。通过调用OpenAI API，实现高质量的代码注释翻译，同时保持原有的代码格式和结构。

🎯 功能特性

• ✅ 智能文件扫描：自动识别Git仓库中的源码文件
• ✅ 多语言支持：支持TypeScript、JavaScript、Go、Markdown等文件格式
• ✅ 精确注释解析：准确定位和提取不同语言的注释内容
• ✅ 高质量翻译：集成OpenAI API，提供专业的翻译服务
• ✅ 格式保持：保持原有的缩进、换行和注释结构
• ✅ 安全备份：自动创建文件备份，支持回滚操作
• ✅ 并发处理：支持并发翻译，提高处理效率
• ✅ 详细报告：生成完整的处理报告和统计信息
• ✅ 函数式设计：采用FP编程范式，代码简洁易维护

🚀 快速开始

安装依赖

npm install

基本使用

# 翻译指定目录下的所有支持文件
ai-translate --root ./src

# 指定文件扩展名
ai-translate --root ./src --exts ts,js,go

# 仅分析不修改（预览模式）
ai-translate --root ./src --dry-run

# 详细输出模式
ai-translate --root ./src --verbose

配置OpenAI API

# 通过环境变量设置
export OPENAI_API_KEY=your-api-key

# 或通过命令行参数
ai-translate --root ./src --openai-key your-api-key

📁 项目结构

src/convert-comments/
├── 📄 requirements.md           # 需求文档
├── 📄 implementation-plan.md    # 实现方案
├── 📄 technical-specification.md # 技术规格
├── 📄 README.md                # 项目概览（本文件）
├── 📦 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/                   # TypeScript类型定义
│   ├── index.ts                # 主要类型定义
│   └── config.ts               # 配置类型
└── 🗂️ __tests__/               # 测试文件
    ├── unit/                   # 单元测试
    └── integration/            # 集成测试

🔧 核心模块

1. 文件扫描模块 (FileScanModule)

• 调用Git命令获取仓库文件列表
• 根据扩展名过滤目标文件
• 识别编程语言类型

2. 中文检测模块 (ChineseDetectionModule)

• 解析不同语言的注释语法
• 识别包含中文字符的注释
• 提取注释的精确位置信息

3. 翻译服务模块 (TranslationModule)

• 调用OpenAI API进行翻译
• 处理翻译错误和重试机制
• 优化翻译提示词和上下文

4. 文件替换模块 (FileReplacementModule)

• 精确替换文件中的中文注释
• 保持代码格式和缩进
• 实现备份和回滚机制

5. 报告生成模块 (ReportModule)

• 收集处理过程的统计信息
• 生成详细的处理报告
• 支持多种输出格式

⚡ 技术亮点

函数式编程范式

采用纯函数设计和不可变数据结构：

const processRepository = pipe(
  getGitTrackedFiles,
  asyncMap(readFile),
  asyncFilter(hasChineseComments),
  asyncMap(extractChineseComments),
  asyncMap(translateComments),
  asyncMap(applyTranslations),
  generateReport
);

性能优化

• 并发控制：使用Semaphore控制API调用频率
• 缓存机制：避免重复翻译相同内容
• 增量处理：仅处理修改过的文件
• 流式处理：支持大文件分块处理

错误处理

• Result模式：使用函数式错误处理
• 重试机制：自动重试失败的API调用
• 部分失败：支持部分文件失败时继续处理

🛠️ 开发指南

环境准备

1. Node.js 环境：建议使用 Node.js 16+
2. TypeScript：项目使用TypeScript开发
3. OpenAI API Key：需要有效的OpenAI API密钥

开发流程

1. 安装依赖

npm install

2. 开发模式运行

npm run dev

3. 运行测试

npm test

4. 构建项目

npm run build

贡献指南

1. Fork 项目到自己的GitHub账号
2. 创建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 创建 Pull Request

代码规范

• TypeScript严格模式：启用所有严格类型检查
• ESLint规则：遵循项目ESLint配置
• Prettier格式化：保持代码格式一致
• 单元测试：新功能需要对应的单元测试

📋 命令行参数

必需参数

• --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>：报告输出文件路径

使用示例

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

# 预览模式（不修改文件）
ai-translate --root ./src --dry-run --verbose

# 使用GPT-4模型
ai-translate --root ./src --model gpt-4

# 生成JSON格式报告
ai-translate --root ./src --output report.json

🔍 配置文件

支持使用配置文件来管理默认设置：

{
  "translation": {
    "model": "gpt-3.5-turbo",
    "maxRetries": 3,
    "timeout": 30000,
    "concurrency": 3
  },
  "processing": {
    "defaultExtensions": ["ts", "js", "go", "md"],
    "createBackup": true,
    "outputFormat": "console"
  },
  "git": {
    "ignorePatterns": ["node_modules/**", ".git/**", "dist/**"],
    "includeUntracked": false
  }
}

📊 输出报告

处理完成后会生成详细的统计报告：

📊 翻译处理报告
==================
总文件数: 45
处理成功: 42
跳过文件: 3
翻译注释: 128
错误数量: 0
处理时间: 45.32秒

✅ 处理完成，无错误

⚠️ 注意事项

API限制

• OpenAI API有调用频率限制，建议合理设置并发数量
• 长时间运行可能消耗较多API配额

翻译质量

• 自动翻译可能不够准确，建议人工审核重要注释
• 提供dry-run模式预览翻译结果

文件安全

• 默认创建备份文件，避免意外损失
• 建议在版本控制环境下使用

🔗 相关文档

• 需求文档 - 详细的功能需求说明
• 实现方案 - 整体架构和设计方案
• 技术规格 - 详细的技术实现规格

📞 问题反馈

如有问题或建议，请通过以下方式联系：

• 创建 GitHub Issue
• 提交 Pull Request
• 发送邮件至开发团队

---

Happy Coding! 🎉