国际化¶

CodexSpec 通过 LLM 动态翻译支持多种语言，并为 GitHub Pages 提供多语言文档。

命令模板翻译¶

工作原理¶

单一英文模板：所有命令模板保持英文
语言配置：项目指定首选输出语言
动态翻译：Claude 在运行时翻译内容

设置语言¶

初始化时¶

# 中文输出
codexspec init my-project --lang zh-CN

# 日语输出
codexspec init my-project --lang ja

初始化后¶

# 查看当前配置
codexspec config

# 更改语言
codexspec config --set-lang zh-CN

# 列出支持的语言
codexspec config --list-langs

配置文件¶

.codexspec/config.yml：

version: "1.0"

language:
  output: "zh-CN"  # 输出语言
  templates: "en"  # 保持为 "en"

project:
  ai: "claude"
  created: "2025-02-15"

GitHub Pages 文档国际化¶

CodexSpec 的文档站点使用 MkDocs 配合 mkdocs-i18n 插件支持 8 种语言。

支持的语言¶

代码	语言
`en`	English（默认）
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

目录结构¶

docs/
├── en/                 # 英文（源）
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # 中文翻译
├── ja/                 # 日语翻译
├── ko/                 # 韩语翻译
├── es/                 # 西班牙语翻译
├── fr/                 # 法语翻译
├── de/                 # 德语翻译
└── pt-BR/              # 葡萄牙语（巴西）翻译

翻译文档¶

使用 /codexspec:translate-docs 命令翻译文档：

# 翻译为中文
/codexspec:translate-docs --lang zh

# 将特定文件翻译为日语
/codexspec:translate-docs user-guide/installation.md --lang ja

# 增量翻译（仅更改的文件）
/codexspec:translate-docs --lang ko --incremental

# 预览模式（不修改文件）
/codexspec:translate-docs --lang es --dry-run

翻译术语表¶

位于 .codexspec/i18n/glossary.yml 的术语表确保术语一致性：

version: "1.0"

# 保持英文的术语
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# 常用术语的翻译
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# 特殊情况的智能规则
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

质量检查¶

结构检查¶

验证所有语言目录具有相同的文件结构：

./scripts/bash/check-i18n-structure.sh

完整性检查¶

检测翻译中未翻译的英文内容：

./scripts/bash/check-i18n-completeness.sh

语义检查¶

AI 驱动的语义一致性分析：

/codexspec:check-i18n-semantics --lang zh

CI/CD 集成¶

.github/workflows/docs-i18n.yml 工作流自动化：

变更检测：当 docs/en/ 更改时触发
并行翻译：所有 7 种目标语言的矩阵策略
质量检查：结构和完整性验证
部署阻止：如果检查失败则阻止部署

手动触发工作流¶

# 通过 GitHub UI 或 CLI
gh workflow run docs-i18n.yml -f languages="zh,ja" -f dry_run="false"

优势¶

零翻译维护：无需维护多个模板版本
始终保持最新：模板更新惠及所有语言
上下文感知：技术术语在适当时保持英文
自动化质量：CI 确保翻译一致性
AI 辅助：Claude 提供上下文感知的翻译