yupanzi
AI OpenSpec Claude

为 OpenSpec 添加多语言支持

· 6 分钟阅读

OpenSpec 是个很棒的规范驱动开发框架，但只支持英文文档。对非英语团队来说，这挺麻烦的。好在 Claude Code 支持自定义命令，我们可以自己动手补上这个功能。

快速上手

一行命令搞定翻译：

# 翻译成中文
/openspec:translate chinese

# 也可以用中文输入
/openspec:translate 中文

# 支持多种语言
/openspec:translate japanese   # 日文
/openspec:translate español    # 西班牙语

核心功能

支持的语言

语言英文名称本地化名称
中文chinese中文
日文japanese日本語
西班牙语spanishespañol
韩语korean한국어
法语frenchfrançais

智能保护机制

翻译时自动保护技术内容：

  • ✅ 代码块原样保留
  • ✅ 文件路径不翻译
  • ✅ 命令示例保持英文
  • ✅ Markdown 结构不破坏
  • ✅ 特殊标记（如 <!-- OPENSPEC:START -->）保持原样

自动更新配置

翻译完成后，命令会自动更新项目配置文件 CLAUDE.md 和 AGENTS.md，添加或更新语言指令。

翻译范围

命令会处理这些文件：

核心文档：

  • openspec/project.md
  • openspec/AGENTS.md

命令文档：

  • .claude/commands/openspec/proposal.md
  • .claude/commands/openspec/apply.md
  • .claude/commands/openspec/archive.md

全局配置（仅 OpenSpec 相关部分）：

  • AGENTS.md
  • CLAUDE.md

排除：.claude/commands/openspec/translate.md（命令本身保持英文）

实现方式

命令文件结构

在项目中创建 .claude/commands/openspec/translate.md：

---
name: OpenSpec: Translate
description: Translate OpenSpec documentation to any target language
category: OpenSpec
tags: [openspec, translation, i18n]
---

<!-- 这里写命令的详细执行指令 -->

工作原理

graph LR
    A[用户输入命令] --> B[Claude 读取命令文件]
    B --> C[解析语言参数]
    C --> D[读取目标文件]
    D --> E[执行翻译]
    E --> F[写回文件]
    F --> G[更新配置]

执行流程：

  1. 提取目标语言（如 chinese → 中文）
  2. 读取每个目标文件
  3. 翻译文本内容，保护技术部分
  4. 写回原文件
  5. 更新语言指令到配置文件

语言映射实现

// 映射表（伪代码）
const languageMap = {
  'chinese': '中文',
  '中文': '中文',
  'japanese': '日本語',
  '日本語': '日本語'
}

// 智能识别
const input = 'chinese'  // 或 '中文'
const target = languageMap[input.toLowerCase()]  // '中文'

完整命令代码

---
name: OpenSpec: Translate
description: Translate OpenSpec documentation to any target language
category: OpenSpec
tags: [openspec, translation, i18n]
---
<!-- OPENSPEC:START -->
**Overview**
This command translates OpenSpec-related documentation from English to a specified target language while preserving technical accuracy and document structure.

**Usage**
`/openspec:translate <language>`


**Examples**
- `/openspec:translate chinese` or `/openspec:translate 中文`
- `/openspec:translate japanese` or `/openspec:translate 日本語`
- `/openspec:translate spanish` or `/openspec:translate español`
- `/openspec:translate korean` or `/openspec:translate 한국어`
- `/openspec:translate french` or `/openspec:translate français`

**Target Files**
The following files will be translated:
- `openspec/project.md`
- `openspec/AGENTS.md`
- `.claude/commands/openspec/proposal.md`
- `.claude/commands/openspec/apply.md`
- `.claude/commands/openspec/archive.md`
- `AGENTS.md` (OpenSpec section only)
- `CLAUDE.md` (OpenSpec section only)

**Excluded Files**
The following files will NOT be translated and always remain in English:
- `.claude/commands/openspec/translate.md` (this command file itself)

**Language Name Mapping**
The system maps English language names to localized names for the language instruction:
- `chinese` or `中文` → "中文"
- `japanese` or `日本語` → "日本語"
- `spanish` or `español` → "español"
- `korean` or `한국어` → "한국어"
- `french` or `français` → "français"

**Process**
1. Extract target language from command arguments
2. Determine the localized language name for the language instruction
3. Read each target file using the Read tool (skip `.claude/commands/openspec/translate.md`)
4. Translate text content to the specified language while preserving:
   - Frontmatter (YAML headers)
   - Code blocks and command examples
   - Markdown structure (headings, lists, links, tables)
   - Special markers (e.g., `<!-- OPENSPEC:START -->`)
   - English commands, file paths, and technical identifiers
5. Write translated content back to original files using the Write tool
6. After translation, append or update language instruction in `CLAUDE.md` and `AGENTS.md`:
   - Check if file ends with "**Always respond in [language]**"
   - If exists, replace with new target language
   - If not exists, append new instruction: "Always respond in [localized language name]"
7. Provide translation progress and completion feedback

**Translation Principles**
- Maintain technical terminology accuracy
- Use natural, idiomatic expressions in the target language
- Preserve all English commands, code, and file paths
- Keep the original document's tone and style
- Support both English language names (e.g., "chinese") and native names (e.g., "中文")

**WARNING**
- Do not translate the command file itself `.claude/commands/openspec/translate.md`
<!-- OPENSPEC:END -->

扩展应用

更多自定义命令示例

代码审查：

---
name: Code Review
description: Generate a comprehensive code review checklist
---
Review the code with focus on:
1. Security vulnerabilities
2. Performance issues
3. Code style consistency
4. Test coverage

文档生成：

---
name: Generate API Docs
description: Auto-generate API documentation from code comments
---
Scan all files in `src/api/` and generate:
- Endpoint descriptions
- Request/response schemas
- Example usage

命令设计原则

原则好的做法不好的做法
清晰性/openspec:translate chinese/t cn
健壮性支持大小写、多种格式只认固定格式
文档性详细的用法示例和参数说明缺少说明文档

项目组织

建议的目录结构：

.claude/
└── commands/
    ├── openspec/        # OpenSpec 相关
    │   ├── translate.md
    │   ├── proposal.md
    │   └── apply.md
    ├── git/             # Git 相关
    │   ├── commit-template.md
    │   └── pr-template.md
    └── docs/            # 文档相关
        ├── api-docs.md
        └── changelog.md

团队协作

把自定义命令加入版本控制：

git add .claude/commands/
git commit -m "feat: add OpenSpec translation command"

团队成员克隆代码后自动获得所有命令。

总结

通过自定义斜杠命令，为 OpenSpec 补上了多语言支持。

简单易用：

  • 一个 Markdown 文件就能定义命令
  • 用自然语言描述指令，无需编程
  • 可以调用所有 Claude Code 工具

实用价值：

  • 补充工具缺失的功能
  • 打造团队专属工作流
  • 沉淀最佳实践

别被工具限制住——通过自定义命令，让 AI 助手真正为你所用。

相关资源：

相关文章