Internationalization¶

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

Command Template Translation¶

How It Works¶

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

Setting Language¶

During Initialization¶

# Chinese output
codexspec init my-project --lang zh-CN

# Japanese output
codexspec init my-project --lang ja

After Initialization¶

# View current configuration
codexspec config

# Change language
codexspec config --set-lang zh-CN

# List supported languages
codexspec config --list-langs

Configuration File¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"  # Output language
  templates: "en"  # Keep as "en"

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

GitHub Pages Documentation i18n¶

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¶

Use the /codexspec.translate-docs command to translate documentation:

# 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 .codexspec/i18n/glossary.yml ensures consistent terminology:

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

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¶

AI-powered semantic consistency analysis:

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

CI/CD Integration¶

The .github/workflows/docs-i18n.yml workflow automates:

Change Detection: Triggers when docs/en/ changes
Parallel Translation: Matrix strategy for all 7 target languages
Quality Checks: Structure and completeness validation
Deployment Blocking: Prevents deployment if checks fail

Manual Workflow Trigger¶

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

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