codei18n

module
v0.0.0-...-be3c4a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 20, 2025 License: GPL-3.0

README

CodeI18n 技术文档

Code Comment Internationalization Infrastructure

CI Go Report Card License Release Go Version

1. 项目定位与问题定义

1.1 项目定位

CodeI18n 是一个面向工程团队的 代码注释国际化基础设施，目标是在不破坏 Git 语义、不污染源码、不影响编译与调试的前提下，实现：

  • 源码仓库统一语言（推荐英文）
  • 本地开发环境以母语阅读和编写注释
  • 注释语言在 Git 提交与 IDE 展示之间自动、可逆转换

CodeI18n 不是简单的“翻译插件”，而是一个 围绕 AST、Git、IDE 的完整工具链。

1.2 要解决的核心问题
问题 传统方案 CodeI18n
注释语言冲突 强制英文 / 中文 英文入库，本地多语言
diff / blame 污染 严重 不污染
多语言协作 成本高 零成本
IDE 体验 无 原生集成
可扩展性 无 AST + Adapter

2. 总体设计目标

2.1 功能目标

  • 支持 多自然语言

    • 默认：英文（en）、中文（zh-CN）
    • 可扩展：ja、ko、fr 等

  • 支持 多编程语言

    • 第一阶段：Go
    • 第二阶段：Rust
    • 第三阶段：JS / TS / Java / Python / C#

  • 支持 多 IDE

    • VS Code
    • JetBrains 家族（IntelliJ / GoLand / RustRover 等）
2.2 非功能目标（硬约束）
  1. Git 仓库中只存在一种注释语言
  2. IDE 展示不修改源码
  3. 所有注释解析必须基于 AST / PSI
  4. 注释翻译必须可逆、可定位
  5. Core 与 IDE 插件解耦

3. 核心设计原则

3.1 单一事实源（Single Source of Truth）
  • 英文注释源码 = 唯一事实源
  • 本地语言注释 = 派生视图
3.2 语义优先，而非文本优先

  • 注释必须绑定到：

    • 文件
    • 语义符号（函数 / 结构体 / 模块）

  • 禁止基于行号、正则处理注释

3.3 Core 与 IDE 解耦

  • Core（Go 实现）

    • 注释解析
    • ID 生成
    • 翻译与映射

  • IDE 插件

    • 只负责渲染
    • 不包含翻译、AST 逻辑

4. 整体系统架构

4.1 架构总览
┌────────────────────────────────────────────┐
│                   IDE Layer                │
│                                            │
│  ┌───────────────┐   ┌──────────────────┐ │
│  │ VS Code       │   │ JetBrains IDEs   │ │
│  │ Extension     │   │ Plugin           │ │
│  └──────▲────────┘   └────────▲─────────┘ │
│         │ Decorations / Inlay           │   │
└─────────┼────────────────────────────────┘
          │ JSON / CLI
┌─────────┴────────────────────────────────┐
│          CodeI18n Core (Go)               │
│  - AST Parsers                            │
│  - Comment Model                          │
│  - Comment ID Generator                   │
│  - Mapping Store                          │
│  - Translation Engine                     │
└─────────▲────────────────────────────────┘
          │ pre-commit
┌─────────┴────────────────────────────────┐
│          Git Hooks / CLI                  │
└─────────▲────────────────────────────────┘
          │
┌─────────┴────────────────────────────────┐
│          Git Remote Repository            │
│        (English-only Source Code)         │
└───────────────────────────────────────────┘

5. CodeI18n Core 设计

5.1 Core 职责
  • 扫描源码并提取注释
  • 为注释生成稳定 ID
  • 管理多语言注释映射
  • 执行注释语言转换（提交前）
  • 为 IDE 提供结构化注释数据
5.2 注释统一抽象模型
type Comment struct {
    ID          string
    File        string
    Language    string          // go / rust / ...
    Symbol      string          // func / struct / impl / module
    Range       TextRange
    SourceText  string          // 英文
}

type LocalizedComment struct {
    CommentID string
    Lang      string            // zh-CN / en / ...
    Text      string
}

6. 注释 ID 设计（关键）

6.1 ID 生成原则

注释 ID 必须满足：

  • 稳定
  • 与代码语义绑定
  • 不依赖行号
6.2 ID 计算方式（推荐）
ID = SHA1(
    file_path +
    language +
    parent_symbol +
    normalized_comment_text
)

📌 parent_symbol 示例：

  • Go：package.func
  • Rust：impl::fn
  • Java：Class#method

7. 多自然语言支持设计

7.1 映射文件结构
{
  "version": "1.0",
  "sourceLanguage": "en",
  "targetLanguage": "zh-CN",
  "comments": {
    "a8f9c3e2": {
      "en": "Calculate account balance",
      "zh-CN": "计算账户余额"
    }
  }
}
7.2 存储策略

  • 默认路径：.codei18n/

  • 映射文件：

    • 本地使用
    • 默认不提交 Git

8. 多编程语言支持策略

8.1 编程语言适配器接口
type LanguageAdapter interface {
    Language() string
    Parse(file string) ([]Comment, error)
}
8.2 Go 语言实现（第一阶段）

  • 使用：

    • go/parser
    • go/ast

  • 支持：

    • //
    • /* */
    • Doc comment

优势：

  • AST 成熟
  • 注释天然绑定节点
8.3 Rust 语言实现（第二阶段）

  • AST 技术路线：

    • syn（通过 sidecar）
    • 或 tree-sitter-rust

  • 处理：

    • //
    • ///
    • /** */
8.4 其他语言（第三阶段）

统一走 Tree-sitter Adapter：

语言 状态
JS / TS 计划
Java 计划
Python 计划
C# 计划

9. IDE 支持设计

9.1 IDE 统一交互模式

IDE 插件通过调用 CLI 获取结构化数据：

codei18n scan --file xxx.go --lang zh-CN --format json

10. VS Code 插件设计

10.1 渲染方式
  • TextEditorDecorationType
  • 覆盖 / 附加显示中文注释
  • 不修改文档内容
after: {
  contentText: "计算账户余额"
}

11. JetBrains IDE 插件设计

11.1 插件类型
  • IntelliJ Platform Plugin
  • Kotlin 实现
  • 多 IDE 共用
11.2 渲染方案（推荐）
Inlay Hint
// Calculate account balance
// ↓ 计算账户余额
  • 使用 InlayModel
  • 官方推荐方式
  • 不影响 PSI / LSP
11.3 备选方案
  • Gutter icon + hover tooltip

12. Git 提交流程设计

12.1 pre-commit Hook
git commit
 └─ pre-commit
    ├─ 扫描 staged 文件
    ├─ 识别非英文注释
    ├─ 翻译为英文
    ├─ 更新映射文件
    └─ 替换源码注释
12.2 行为原则
  • 只处理 staged 文件
  • 翻译失败可阻断提交（可配置）

13. 翻译引擎设计

13.1 抽象接口
type Translator interface {
    Translate(text, from, to string) (string, error)
}
13.2 实现策略

  • 本地缓存优先，优先复用已有翻译结果，减少对外部服务的调用频率。

  • 支持的翻译后端（通过 translationProvider 选择）：

    • openai / llm：基于 OpenAI 兼容协议的远程 LLM（如官方 OpenAI、DeepSeek 或自建代理），使用 OPENAI_API_KEY 和可选 OPENAI_BASE_URL。
    • ollama：本地 Ollama 服务，通过 REST API 调用本地模型（如 llama3、qwen3 等）。
    • mock：仅用于测试和集成测试场景，不用于生产环境。

  • 避免在 Git 提交路径上频繁同步调用大模型，可通过预翻译批量填充映射文件。

13.3 翻译服务配置示例

CodeI18n 的翻译服务配置由两部分组成：

  1. 顶层字段：translationProvider（选择后端）
  2. 细节字段：translationConfig（不同后端的参数）
13.3.1 使用 OpenAI / DeepSeek / 兼容 LLM
{
  "sourceLanguage": "en",
  "localLanguage": "zh-CN",
  "translationProvider": "openai",
  "translationConfig": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4.1-mini"
  },
  "batchSize": 10
}

运行前需要配置环境变量：

export OPENAI_API_KEY="your-api-key"
# 可选：自建代理或第三方 OpenAI 兼容服务
export OPENAI_BASE_URL="https://api.openai.com/v1"

如果 model 设置为 deepseek-chat 或 deepseek-coder，系统会自动将 baseUrl 设为 https://api.deepseek.com，也可以手动通过 baseUrl 显式指定其他兼容服务。

13.3.2 使用本地 Ollama
{
  "sourceLanguage": "en",
  "localLanguage": "zh-CN",
  "translationProvider": "ollama",
  "translationConfig": {
    "endpoint": "http://localhost:11434",
    "model": "qwen3:4b"
  },
  "batchSize": 5
}

说明：

  • endpoint：Ollama HTTP 服务地址，默认 http://localhost:11434。
  • model：本地已拉取的模型名称，例如 qwen3:4b、llama3 等。
  • CodeI18n 在调用 Ollama 时会显式设置 "think": false，关闭思维链模式，避免额外的延迟和算力消耗。

启用本地 Ollama 集成测试示例（非必须）：

CODEI18N_OLLAMA_TEST=1 \
CODEI18N_OLLAMA_MODEL=qwen3:4b \
go test ./adapters/translator -run TestOllamaTranslator_Translate_Integration -v
13.3.3 通过 CLI 覆盖配置

在 .codei18n/config.json 配置好默认翻译服务后，也可以在命令行临时覆盖：

# 覆盖 provider 为 openai
codei18n translate --provider openai

# 覆盖 provider 为本地 ollama
codei18n translate --provider ollama

# 临时指定模型（会覆盖 translationConfig.model）
codei18n translate --model gpt-4.1-mini
13.3.4 从 Google / DeepL 迁移

历史版本中可能使用过 translationProvider: "google" 或 "deepl"。迁移建议：

  1. 打开 .codei18n/config.json，删除或重命名以下配置：
    • 将 "translationProvider": "google" 或 "deepl" 改为 "openai" 或 "ollama"；
    • 如有旧的 google/deepl 相关字段，可以移除，仅保留 baseUrl/model 等通用字段。
  2. 为 openai 模式配置：
    • 设置 translationProvider: "openai"；
    • 在 translationConfig 中指定 model，必要时指定 baseUrl；
    • 在环境中配置 OPENAI_API_KEY（以及可选的 OPENAI_BASE_URL）。
  3. 或者切换到本地 ollama 模式：
    • 设置 translationProvider: "ollama"；
    • 在 translationConfig 中设置 endpoint 和本地模型名称；
  4. 运行：
codei18n translate

确认命令可以正常执行且不会再出现“翻译提供商 google/deepl 已不再支持”的错误提示。

14. 配置文件设计

{
  "sourceLanguage": "en",
  "localLanguage": "zh-CN",
  "ide": {
    "vscode": {
      "displayMode": "overlay"
    },
    "jetbrains": {
      "displayMode": "inlay"
    }
  }
}

15. 项目目录结构建议

CodeI18n/
├─ cmd/codei18n
├─ core/
│  ├─ comment/
│  ├─ mapping/
│  ├─ translate/
├─ adapters/
│  ├─ go/
│  ├─ rust/
│  └─ treesitter/
├─ ide/
│  ├─ vscode/
│  └─ jetbrains/
├─ docs/
└─ examples/

16. 开发工作流与 Makefile

本项目提供了完整的 Makefile 来简化日常开发操作。

16.1 常用命令
# 查看所有可用命令
make help

# 构建可执行文件
make build

# 运行所有测试（跳过集成测试）
make test

# 运行所有测试（包括集成测试，需要有效的 API key）
make test-integration

# 生成测试覆盖率报告
make coverage

# 查看 HTML 格式的覆盖率报告
make coverage-html

# 格式化代码
make fmt

# 运行代码检查
make lint

# 运行所有质量检查（fmt + vet + lint）
make check

# 开发模式：快速检查
make dev

# 完整 CI 流程
make all

# CI/CD 模式（包含覆盖率验证）
make ci

# Pre-commit 检查
make pre-commit
16.2 代码质量要求

根据项目章程要求：

  • 总体测试覆盖率: ≥ 60%
  • 核心模块覆盖率: ≥ 80%（core/comment, core/mapping, core/translate）
  • 代码规范: 必须通过 gofmt 和 golint/staticcheck 检查

使用以下命令验证：

# 检查覆盖率是否达标
make coverage-check

# 运行完整的 CI 检查
make ci
16.3 开发工作流示例
日常开发
# 1. 编写代码
# 2. 快速验证
make dev

# 3. 提交前检查
make pre-commit

# 4. 构建
make build
提交前完整检查
# 运行完整 CI 流程
make ci
16.4 Docker 支持

项目支持 Docker 容器化部署：

# 构建 Docker 镜像
make docker-build

# 运行 Docker 容器
make docker-run

# 在 Docker 中运行测试
make docker-test

# 清理 Docker 镜像
make docker-clean
16.5 CI/CD 集成

项目配置了完整的 GitHub Actions CI/CD 流程：

自动化检查

每次 push 或 pull request 时自动运行：

  • ✅ 代码质量检查（gofmt、go vet、staticcheck）
  • ✅ 多平台构建测试（Linux、macOS、Windows）
  • ✅ 单元测试和覆盖率报告
  • ✅ 集成测试
  • ✅ 安全扫描（gosec、govulncheck）
  • ✅ 依赖审计
自动发布

推送版本 tag 时自动构建和发布：

# 创建版本 tag
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

# GitHub Actions 将自动：
# - 构建多平台二进制文件
# - 生成 Release Notes
# - 创建 GitHub Release
# - 构建并推送 Docker 镜像（如果配置）

更多详情请查看 CI/CD 工作流说明。

17. Roadmap（明确可执行）

v0.1
  • Go AST
  • CLI
  • VS Code
v0.2
  • Rust
  • pre-commit
  • JetBrains（GoLand / RustRover）
v0.3
  • Tree-sitter
  • JS / TS / Java

18. 结论

CodeI18n 本质是一个“代码注释 i18n 基础设施”：

  • Git 负责事实
  • AST 负责语义
  • IDE 负责体验

这是一个 长期存在、但一直没人系统解决的问题。

Directories

Path Synopsis
golang
java
rust
translator
typescript
cmd
codei18n command
config
domain
mapping
scanner
utils
workflow
internal
log
specs
001-codei18n-core-mvp/contracts
tests
fixtures

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.