国际化¶

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

命令模板翻译¶

工作原理¶

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

语言维度¶

CodexSpec 把语言拆分为四个可独立配置的维度。output 是基础；其余三项覆盖它，并在未设置时回退到它（再到 en）。

维度	`config.yml` 键	初始化时设置	之后设置	控制	回退到
Output（基础）	`output`	`--lang`	`config --set-lang`	其他三项的基础	`en`
Interaction	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	LLM 对话 + CLI 输出	output → `en`
Document	`document`	`--document-lang`	`config --set-document-lang`	生成的 spec/plan/tasks	output → `en`
Commit	`commit`	`--commit-lang`	`config --set-commit-lang`	git 提交信息	output → `en`
Templates	`templates`	—	—	命令模板来源（始终为 `en`）	—

设置语言¶

初始化时¶

# 中文输出（设置 output 基础语言）
codexspec init my-project --lang zh-CN

# 完全非交互：zh-CN 基础语言，英文提交信息
codexspec init my-project --lang zh-CN --commit-lang en

# 显式设置每个维度（可脚本化，无提示）
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

在 TTY 中首次运行 init 且未指定 --lang（也未同时指定全部三个维度标志）时会提示选择基础语言；在非 TTY 环境（CI/脚本）下默认为 en。重新运行 init 会保留你未显式指定的任何语言键。

初始化后¶

# 查看当前配置
codexspec config

# 更改单个维度
codexspec config --set-lang zh-CN
codexspec config --set-interaction-lang zh-CN
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# 切换 workflow.auto_next（裸标志切换；也可显式传入 on/off）
codexspec config --auto-next

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

配置文件¶

.codexspec/config.yml：

version: "1.0"

language:
  output: "zh-CN"        # 基础语言；以下三项回退到它，再到 "en"
  interaction: "zh-CN"   # LLM 对话 + codexspec CLI 输出（可选 → 默认为 output）
  document: "en"         # 生成的 requirements/spec/plan/tasks（可选 → 默认为 output）
  commit: "en"           # git 提交信息（可选 → 默认为 output）
  templates: "en"        # 保持为 "en"

project:
  ai: "claude"          # claude | codex | both — 本项目面向哪种 AI 助手
  created: "2025-02-15"

GitHub Pages 文档国际化¶

文档站点语言与 CLI/运行时语言——不要混淆。

文档站点（本节）：8 种语言。 由 MkDocs 构建的 GitHub Pages 站点只发布下方列出的八个语言版本（en、zh、ja、ko、es、fr、de、pt-BR）。这是一个固定集合，由 docs/{lang}/ 目录结构与 mkdocs-i18n 插件共同决定。

CLI / 运行时（上一节）：13 种语言。 你在 .codexspec/config.yml 里配置的 language.* 维度接受 13 个受支持的语言代码（en、zh-CN、zh-TW、ja、ko、es、fr、de、pt-BR、ru、it、ar、hi），由 LLM 实时翻译。规范的列表见项目 README 中的“Supported Languages”表格。

两组语言有重叠但不相同：文档站点没有 zh-TW/ru/it/ar/hi 版本；而 CLI 也不使用 MkDocs 作为目录名的裸 zh/de/... 代码。

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:check-i18n-semantics 命令是 CodexSpec 维护者专用工具。它们与本仓库的 MkDocs 多语言目录结构（docs/{lang}/）以及仅存于本仓库的术语表 docs/i18n/glossary.yml 紧密耦合。它们不会通过 codexspec init 分发到用户项目，也不作为面向终端用户的斜杠命令提供。

如果你正在开发 CodexSpec 本身，这两个命令位于 .claude/commands/codexspec/，调用方式与其他斜杠命令相同。需要翻译自己项目文档的终端用户，请直接使用 Claude，结合自己偏好的工作流完成。

CodexSpec 维护者可以使用 /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

翻译术语表¶

位于 docs/i18n/glossary.yml（仅仓库内）的术语表，确保翻译 CodexSpec 自身文档时术语一致：

version: "1.0"

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

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

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

翻译方法论¶

译文力求用你的语言自然表达，而不是逐字照搬英文：

意思优先。 每段文字先理解它要传达的内容，再用目标语言自己的措辞与句式重新表达。
英文术语更清晰时保留英文。 没有合适母语对应、或在英文中更易识别的技术术语，保留英文而不是生硬翻译。例如 "AI coding agent" 译成 "AI 编程助手" 这样的自然说法，而不是生硬直译。
母语流畅。 目标是读起来像原本就用你的语言写成的一样。

质量检查¶

结构检查¶

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

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

完整性检查¶

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

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

语义检查（仅限维护者）¶

AI 驱动的语义一致性分析仅对 CodexSpec 维护者开放，通过内部命令调用（详见上文的“仅限维护者”说明）：

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

CI/CD 集成¶

.github/workflows/docs-i18n.yml 工作流仅用作构建关卡：每当 docs/** / mkdocs.yml 发生变更（推送到 main 以及 Pull Request）时，它会在所有语言版本上运行 mkdocs build --strict，以捕获构建错误、断链和格式错误的内容。它不会翻译任何东西。

翻译通过 /codexspec:translate-docs（见上文）手动生成并提交，英文源文件与所有译文出现在同一个经过审阅的原子提交里。CI 中的自动翻译已被有意移除——此前的那个任务从未真正运行过（一个格式错误的 if 跳过了它）、还需要常驻的 API key，而且会把未经审阅的译文直接提交到 main。

优势¶

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