AI 原生开放教材

外观

Coze Studio 源码研读源码研读·中英混排原文 ↗仓库 ↗

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

📖 项目简介 ​

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

🎯 功能特性 ​

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

🚀 快速开始 ​

安装依赖 ​

bash
npm install

基本使用 ​

bash
# 翻译指定目录下的所有支持文件
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 ​

bash
# 通过环境变量设置
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) ​

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

⚡ 技术亮点 ​

函数式编程范式 ​

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

typescript
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. 安装依赖
bash
npm install
  1. 开发模式运行
bash
npm run dev
  1. 运行测试
bash
npm test
  1. 构建项目
bash
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>：报告输出文件路径

使用示例 ​

bash
# 基本使用
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

🔍 配置文件 ​

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

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! 🎉