Internationalization¶
Configuration lives in .codexspec/config.yml. Templates stay in English;
agents write interaction text and generated artifacts in the configured languages.
The 13 standard language codes are en, zh-CN, zh-TW, ja, ko,
es, fr, de, pt, ru, it, ar, and hi.
The Portuguese CLI code is pt; localized documentation and translation
catalogs use pt-BR.
Language Dimensions¶
| Dimension | Config key | At initialization | Set later | Controls |
|---|---|---|---|---|
| Output/base | language.output |
--lang |
config --set-lang |
Fallback for the other language dimensions |
| Interaction | language.interaction |
--interaction-lang |
config --set-interaction-lang |
Conversation and CLI output |
| Document | language.document |
--document-lang |
config --set-document-lang |
Requirements, specifications, designs, plans, tasks |
| Commit | language.commit |
--commit-lang |
config --set-commit-lang |
Commit messages and Git-delivery content |
Each specific language falls back independently to language.output, then en.
language.templates remains 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
First-time TTY initialization prompts for the base language unless you supply
--lang or all three specific language options. --force auto-confirms other
initialization prompts; it does not suppress this language selection.
Non-TTY initialization defaults to English. Re-initialization preserves language
keys you did not explicitly set.
Translated documentation¶
The site and root READMEs have eight maintained language versions. Runtime language settings control agent output; they do not automatically translate repository documentation. English site pages in docs/en/ are the translation source. English is served at the site root, and the other versions under their locale paths.
English · 中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português
Maintaining translations¶
Use the repository-only translation and semantic-review entries in either assistant. They are maintainer tools, not public commands installed by codexspec init. The shared rules are in internal/references/doc-translation.md, and terminology is in 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
Select the changed English pages, read the complete source, and preserve every condition, default, exclusion, example, and technical token. Write natural technical prose in the target language; preserving English sentence structure is not a requirement. Review fidelity and natural expression separately, and verify translated heading links against their destination pages.
The inventory records exact source/target pairs and source hashes. Mechanical checks catch structural, code-example, token, and link differences; they do not establish semantic equivalence. Review every selected language and repair omissions or unnatural wording before accepting the translation. A dry run only previews the selection.
Build and diagram checks¶
The documentation CI builds with strict MkDocs validation. Translation and semantic review remain explicit maintenance work; a successful build alone does not establish translation quality. Preview the affected pages, language navigation, narrow layouts, and both themes.
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
The site reuses the README workflow PNGs from assets/workflow/ through hooks/workflow_assets.py; it does not keep a second set of source images under the documentation directories. Theme-specific image links follow the site’s light/dark toggle. Update the diagram source, catalogs, layout, and all generated assets using the shared maintenance handbook.