Skip to content

Internationalization

CodexSpec supports multiple languages through LLM dynamic translation and provides multi-language documentation for GitHub Pages.

Command Template Translation

How It Works

  1. Single English Templates: All command templates remain in English
  2. Language Configuration: Project specifies preferred output language
  3. Dynamic Translation: Claude translates content at runtime

Language Dimensions

CodexSpec splits language into four independently-configurable dimensions. output is the base; the others override it and fall back to it (then en) when unset.

Dimension config.yml key Set at init Set later Controls Falls back to
Output (base) output --lang config --set-lang base for the other three en
Interaction interaction --interaction-lang config --set-interaction-lang LLM dialogue + CLI output output → en
Document document --document-lang config --set-document-lang generated spec/plan/tasks output → en
Commit commit --commit-lang config --set-commit-lang git commit messages output → en
Templates templates — — command template source (always en) —

Setting Language

During Initialization

# Chinese output (sets the output base)
codexspec init my-project --lang zh-CN

# Fully non-interactive: zh-CN base, English commit messages
codexspec init my-project --lang zh-CN --commit-lang en

# Set every dimension explicitly (scriptable, no prompts)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

First-time init in a TTY without --lang (and without all three dimension flags) prompts for a base language; in a non-TTY (CI/scripts) it defaults to en. Re-running init preserves any language key you did not specify.

After Initialization

# View current configuration
codexspec config

# Change a single dimension
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

# Toggle workflow.auto_next (bare flag toggles; or pass on/off explicitly)
codexspec config --auto-next

# List supported languages
codexspec config --list-langs

Configuration File

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # Base language; the three below fall back to it, then "en"
  interaction: "zh-CN"   # LLM dialogue + codexspec CLI output (optional → defaults to output)
  document: "en"         # Generated requirements/spec/plan/tasks (optional → defaults to output)
  commit: "en"           # Git commit messages (optional → defaults to output)
  templates: "en"        # Keep as "en"

project:
  ai: "claude"          # claude | codex | both — which AI assistant this project targets
  created: "2025-02-15"

GitHub Pages Documentation i18n

Docs-site languages vs. CLI/runtime languages — don't conflate them.

  • Documentation site (this section): 8 languages. The GitHub Pages site built by MkDocs ships exactly the eight locales listed below (en, zh, ja, ko, es, fr, de, pt-BR). This is a fixed set, governed by the docs/{lang}/ directory layout and the mkdocs-i18n plugin.
  • CLI / runtime (the section above): 13 languages. The language.* dimensions you configure in .codexspec/config.yml accept 13 supported codes (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi), translated on the fly by the LLM. See the "Supported Languages" table in the project README for the canonical list.

The two sets overlap but are not identical: the docs site has no zh-TW/ru/it/ar/hi locales, and the CLI does not use the bare zh/de/... codes that MkDocs uses as folder names.

CodexSpec's documentation site supports 8 languages using MkDocs with the mkdocs-i18n plugin.

Supported Languages

Code Language
en English (default)
zh 中文简体
ja 日本語
ko 한국어
es Español
fr Français
de Deutsch
pt-BR Português (Brasil)

Directory Structure

docs/
├── en/                 # English (source)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # Chinese translation
├── ja/                 # Japanese translation
├── ko/                 # Korean translation
├── es/                 # Spanish translation
├── fr/                 # French translation
├── de/                 # German translation
└── pt-BR/              # Portuguese (Brazil) translation

Translating Documentation (Maintainer-Only)

Note: The /codexspec:translate-docs and /codexspec:check-i18n-semantics commands are CodexSpec maintainer tooling. They are tightly coupled to this repository's MkDocs i18n layout (docs/{lang}/) and the repo-only glossary at docs/i18n/glossary.yml. They are not distributed to user projects via codexspec init and are not available as user-facing slash commands.

If you are working on CodexSpec itself, these commands live in .claude/commands/codexspec/ and are invoked the same way as any other slash command. End users translating their own project documentation should use Claude directly with their preferred workflow.

For CodexSpec maintainers, use the /codexspec:translate-docs command to translate the docs:

# Translate to Chinese
/codexspec:translate-docs --lang zh

# Translate specific file to Japanese
/codexspec:translate-docs user-guide/installation.md --lang ja

# Incremental translation (only changed files)
/codexspec:translate-docs --lang ko --incremental

# Preview mode (no file changes)
/codexspec:translate-docs --lang es --dry-run

Translation Glossary

The glossary at docs/i18n/glossary.yml (repo-only) ensures consistent terminology when translating CodexSpec's own documentation:

version: "1.0"

# Terms to keep in English
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Translations for common terms
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# Smart rules for special cases
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

Translation Methodology

Translations aim to read naturally in your language, not as word-for-word renderings of the English:

  • Meaning first. Each passage is translated for what it communicates, then re-expressed using the target language's own phrasing and sentence structure.
  • English terms stay when they are clearer. Technical terms with no good native equivalent — or that are more recognizable in English — are kept in English rather than translated awkwardly. For example, "AI coding agent" becomes a natural native phrase such as "AI 编程助手", not a stiff literal.
  • Native fluency. The goal is prose that reads as if it were originally written in your language.

Quality Checks

Structure Check

Verifies all language directories have the same file structure:

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

Completeness Check

Detects untranslated English content in translations:

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

Semantic Check (Maintainer-Only)

AI-powered semantic consistency analysis, available to CodexSpec maintainers via the internal command (see the maintainer-only note above):

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

CI/CD Integration

The .github/workflows/docs-i18n.yml workflow is a build gate only: on every docs/** / mkdocs.yml change (push to main and pull requests) it runs mkdocs build --strict across all language versions to catch build errors, broken links, and malformed content. It does not translate anything.

Translations are produced and committed manually via /codexspec:translate-docs (see above), with the English source and all translations in one reviewed, atomic commit. Auto-translation in CI was intentionally removed — the earlier job never actually ran (a malformed if skipped it), required a standing API key, and would have committed unreviewed translations directly to main.

Benefits

  • Zero Translation Maintenance: No need to maintain multiple template versions
  • Always Up-to-Date: Template updates benefit all languages
  • Context-Aware: Technical terms remain in English when appropriate
  • Automated Quality: CI ensures translation consistency
  • AI-Assisted: Claude provides context-aware translations