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

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 (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

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 automates:

  1. Change Detection: Triggers when docs/en/ changes
  2. Parallel Translation: Matrix strategy for all 7 target languages
  3. Quality Checks: Structure and completeness validation
  4. 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