国际化¶
配置保存在 .codexspec/config.yml 中。模板始终使用英文，智能体交流和生成文档时，则使用配置中指定的语言。支持的 13 个标准语言代码为 en、zh-CN、zh-TW、ja、ko、es、fr、de、pt、ru、it、ar 和 hi。葡萄牙语在 CLI 中使用 pt，在本地化文档和翻译目录中使用 pt-BR。
语言维度¶
| 维度 | 配置键 | 初始化时 | 后续设置 | 控制范围 |
|---|---|---|---|---|
| 输出/基础 | language.output |
--lang |
config --set-lang |
其他语言选项未设置时使用的语言 |
| 交互 | language.interaction |
--interaction-lang |
config --set-interaction-lang |
对话和 CLI 输出 |
| 文档 | language.document |
--document-lang |
config --set-document-lang |
需求、规格、设计、计划、任务 |
| 提交 | language.commit |
--commit-lang |
config --set-commit-lang |
提交信息及 Git 工作流生成的文本 |
每项语言设置都独立生效：未指定时先使用 language.output，它也未指定时再使用 en。language.templates 始终为 en。
codexspec init my-project --ai both \
--interaction-lang zh-CN --document-lang en --commit-lang en
codexspec config
codexspec config --set-document-lang en
codexspec config --list-langs
首次在交互式终端（TTY）中初始化时，如果没有指定 --lang，也没有完整指定三个具体语言选项，程序会询问基础语言。--force 会自动确认其他初始化提示，但仍会要求选择语言。在非 TTY 环境中初始化时，默认使用英文。重新初始化时，没有明确修改的语言设置会保留。
多语言文档¶
文档站和根目录 README 维护八种语言版本。运行时语言设置控制智能体的输出，不会自动翻译仓库文档。docs/en/ 中的英文页面是站点翻译源；英文发布在站点根路径，其他版本发布在各自的语言路径下。
English · 中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português
维护译文¶
两种助手都可使用仓库专用的翻译与语义审查入口。这些是维护工具，不属于 codexspec init 安装的公开命令。共享规则位于 internal/references/doc-translation.md，术语表位于 docs/i18n/glossary.yml。
$codexspec:translate-docs --source docs/en/getting-started/installation.md --lang all
$codexspec:check-i18n-semantics --source docs/en/getting-started/installation.md --lang all --strict
/codexspec:translate-docs --source docs/en/getting-started/installation.md --lang all
/codexspec:check-i18n-semantics --source docs/en/getting-started/installation.md --lang all --strict
选定有变更的英文页面后，通读完整源文，保留所有条件、默认值、排除范围、示例和技术标记。译文应符合目标语言的技术文档表达习惯，不必沿用英文句式。分别检查语义忠实度和表达自然度，并根据目标页面核验译文中的标题链接。
清单会记录准确的源文件／目标文件配对及源文件哈希。机械检查可以发现结构、代码示例、技术标记和链接差异，但不能证明语义一致。每种选定语言都需要审查，修复遗漏与生硬表达后才能接受译文。预演只展示选择范围。
构建与图表检查¶
文档 CI 使用 MkDocs 严格验证构建。翻译与语义审查仍需明确执行，构建成功本身不能证明翻译质量。应预览受影响页面、语言导航、窄屏布局以及浅色和暗色主题。
uv sync --extra dev --extra docs
uv run python -B -m internal.doc_translation inventory --lang all
uv run python -B -m internal.doc_translation verify --lang all
uv run mkdocs build --strict
uv run mkdocs serve
站点通过 hooks/workflow_assets.py 复用 assets/workflow/ 中的 README 流程图 PNG，不在文档目录中另存一套源图片。主题专用图片链接会随站点的浅色／暗色开关切换。更新图表时，按共享维护手册修改源图、翻译表和布局，并重新生成全部资源。