Table of Contents

Internationalization (i18n) Guide

Spec Kit supports multiple languages for commands, templates, and CLI messages.

Supported Languages

  • English (en): Default language, always included
  • Korean (ko): Full translation available

Architecture

Spec Kit uses a hybrid i18n approach:

  1. Default language (English) is bundled with the main package
  2. Additional languages can be installed separately (feature coming soon)
  3. Language detection is automatic based on system locale or environment variables

Directory Structure

spec-mix/
├── locales/
│   ├── config.json                # Language configuration
│   ├── en/                        # English (default)
│   │   ├── strings.json           # CLI messages
│   │   ├── commands/              # Command instructions
│   │   │   ├── specify.md
│   │   │   ├── plan.md
│   │   │   └── ...
│   │   └── templates/             # Document templates
│   │       ├── spec-template.md
│   │       ├── plan-template.md
│   │       └── ...
│   └── ko/                        # Korean
│       ├── strings.json
│       ├── commands/
│       └── templates/

Using Spec Kit in Different Languages

Automatic Language Detection

Spec Kit automatically detects your language based on:

  1. SPECIFY_LANG environment variable (highest priority)
  2. System locale (LANG, LC_ALL)
  3. Default language (English) if none detected

Setting Language Manually

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export SPECIFY_LANG=ko

Option 2: Per-Session

SPECIFY_LANG=ko spec-mix init my-project

Option 3: Using the CLI

# List available languages
spec-mix lang list

# Show current language
spec-mix lang current

# Set default language (updates environment variable recommendation)
spec-mix lang set ko

Language Management Commands

spec-mix lang list

Lists all available and installed languages:

$ spec-mix lang list

Available Languages
┌──────────┬────────────────────────┬─────────────────────────┐
│ Code     │ Name                   │ Status                  │
├──────────┼────────────────────────┼─────────────────────────┤
│ en       │ English (English)      │ Installed, Default      │
│ ko       │ 한국어 (Korean)         │ Installed               │
└──────────┴────────────────────────┴─────────────────────────┘

Current language: English (English)

spec-mix lang current

Shows the currently active language:

$ spec-mix lang current

Current language: 한국어 (Korean) (ko)

To change language:
  spec-mix lang set <code>

To list available languages:
  spec-mix lang list

spec-mix lang set <code>

Sets the default language and provides instructions for making it permanent:

$ spec-mix lang set ko

Default language set to: 한국어 (Korean)

To make this permanent, add to your shell profile:
  export SPECIFY_LANG=ko

spec-mix lang install <code> (Coming Soon)

Installs a language pack from GitHub releases:

$ spec-mix lang install ko

Installing language pack: ko
Downloading from GitHub releases...

[Feature Coming Soon]
Language pack installation from GitHub releases is not yet implemented.
For now, language packs are bundled with the main package.

How Language Selection Works

Template and Command Loading

When you run a command like /spec-mix.specify:

  1. Spec Kit checks the current language setting
  2. Loads the appropriate command file from locales/{lang}/commands/specify.md
  3. Uses templates from locales/{lang}/templates/
  4. Falls back to English if translation is missing

CLI Messages

All CLI messages (errors, success messages, prompts) are translated using the strings.json file:

# In Python code
from specmix.i18n import t

# Translate a message
message = t('cli.init.project_ready')  # English: "Project ready."
                                       # Korean: "프로젝트가 준비되었습니다."

# With format arguments
message = t('cli.init.error_invalid_ai', ai='claude', options='claude, copilot')

Adding a New Language

1. Create Language Directory

mkdir -p locales/{lang_code}/{commands,templates}

2. Add to Configuration

Edit locales/config.json:

{
  "supported_locales": [
    {
      "code": "en",
      "name": "English",
      "native_name": "English",
      "is_default": true
    },
    {
      "code": "ja",
      "name": "Japanese",
      "native_name": "日本語",
      "is_default": false
    }
  ]
}

3. Translate Strings

Create locales/{lang_code}/strings.json with all CLI messages translated.

Use locales/en/strings.json as reference.

4. Translate Commands

Copy command files from locales/en/commands/ and translate:

  • specify.md - Feature specification workflow
  • constitution.md - Project constitution workflow
  • plan.md - Implementation planning workflow
  • tasks.md - Task breakdown workflow
  • implement.md - Implementation execution workflow
  • clarify.md - Clarification workflow
  • analyze.md - Analysis workflow
  • checklist.md - Checklist generation workflow

5. Translate Templates

Copy template files from locales/en/templates/ and translate:

  • spec-template.md - Feature specification template
  • plan-template.md - Implementation plan template
  • tasks-template.md - Task breakdown template
  • checklist-template.md - Quality checklist template

6. Test the Translation

SPECIFY_LANG={lang_code} spec-mix init test-project

Fallback Behavior

If a translation is missing:

  1. String not found: Shows [MISSING: key.path]
  2. Command file not found: Falls back to English
  3. Template not found: Falls back to English

This ensures Spec Kit always works, even with partial translations.

Technical Implementation

LocaleManager Class

The LocaleManager class (src/specmix/i18n.py) handles:

  • Locale detection
  • String loading with fallback
  • Deep merging of translations
  • Template path resolution

Key Functions

from specmix.i18n import get_locale_manager, t, init_i18n

# Initialize i18n (done automatically by CLI)
init_i18n()

# Get current locale manager
lm = get_locale_manager()

# Translate a string
message = t('cli.init.project_ready')

# Check current locale
current_lang = lm.current_locale  # e.g., "ko"

# Get available locales
installed = lm.get_installed_locales()  # ['en', 'ko']
supported = lm.get_supported_locales()  # Full config list

Best Practices

For Users

  1. Set language once: Use SPECIFY_LANG environment variable
  2. Check available languages: Run spec-mix lang list to see what's available
  3. Report translation issues: Open GitHub issue if translations are incorrect

For Contributors

  1. Keep translations consistent: Use the same terminology throughout
  2. Preserve formatting: Maintain markdown formatting, placeholders, etc.
  3. Test thoroughly: Run through full workflow in translated language
  4. Update all files: When adding new features, update all language files

Troubleshooting

Language not being detected

# Check current language
spec-mix lang current

# Set explicitly
export SPECIFY_LANG=ko
spec-mix lang current

Partial English in translated interface

This means some strings are not yet translated. Check:

  1. locales/{lang}/strings.json for missing CLI messages
  2. locales/{lang}/commands/ for missing command translations
  3. locales/{lang}/templates/ for missing template translations

Cannot install language pack

Language pack installation from GitHub releases is coming in a future update. For now, all supported languages are bundled with the main package.

Future Enhancements

  • [ ] Download language packs from GitHub releases
  • [ ] Community-contributed translations
  • [ ] Translation completeness checking tool
  • [ ] In-app language switching without restart
  • [ ] Regional variants (en-US, en-GB, zh-CN, zh-TW)
Edit this page