codexspec 0.6.2__tar.gz → 0.6.4__tar.gz

{codexspec-0.6.2 → codexspec-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.6.2
+Version: 0.6.4
 Summary: CodexSpec - A Requirements-First SDD toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -528,12 +528,15 @@ Implementation follows **conditional TDD workflow**:
 
 | Option          | Description                           |
 | --------------- | ------------------------------------- |
-| `PROJECT_NAME`  | Project directory name                |
-| `--here`, `-h`  | Initialize in current directory       |
+| `PROJECT_NAME`  | Project directory name (`.` or `--here` for current dir) |
+| `--here`, `-h`  | Initialize in the current directory   |
 | `--ai`, `-a`    | AI assistant to use (default: claude) |
-| `--lang`, `-l`  | Output language (e.g., en, zh-CN, ja) |
-| `--force`, `-f` | Force overwrite existing files        |
-| `--no-git`      | Skip git initialization               |
+| `--lang`, `-l`  | Output (base) language; interaction/document/commit fall back to it (e.g., en, zh-CN, ja) |
+| `--interaction-lang` | Interaction language (LLM dialogue + CLI output); overrides `--lang` |
+| `--document-lang` | Document language (generated spec/plan/tasks); overrides `--lang` |
+| `--commit-lang` | Commit-message language; overrides `--lang` |
+| `--force`, `-f` | Overwrite files + auto-confirm prompts; never regenerates `config.yml` |
+| `--no-git`      | Skip git repository initialization    |
 | `--debug`, `-d` | Enable debug output                   |
 
 </details>
@@ -543,8 +546,10 @@ Implementation follows **conditional TDD workflow**:
 
 | Option                    | Description                  |
 | ------------------------- | ---------------------------- |
-| `--set-lang`, `-l`        | Set output language          |
-| `--set-commit-lang`, `-c` | Set commit message language  |
+| `--set-lang`, `-l`        | Set the output (base) language |
+| `--set-interaction-lang`  | Set the interaction language |
+| `--set-document-lang`     | Set the document language    |
+| `--set-commit-lang`, `-c` | Set the commit-message language |
 | `--list-langs`            | List all supported languages |
 
 </details>
@@ -628,28 +633,46 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 
 CodexSpec supports multiple languages through **LLM dynamic translation**. No translation templates to maintain - Claude translates content at runtime based on your language configuration.
 
+### 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 — so you can converse with Claude in one language while keeping generated artifacts or commit messages in another.
+
+| 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` | — | — | template source (always `en`) | — |
+
 ### Setting Language
 
 **During initialization:**
 
 ```bash
-# Create Chinese output project
+# Chinese output (sets the output base)
 codexspec init my-project --lang zh-CN
 
-# Create Japanese output project
-codexspec init my-project --lang ja
+# 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:**
 
 ```bash
 # View current configuration
 codexspec config
 
-# Change output language
+# Change a single dimension
 codexspec config --set-lang zh-CN
-
-# Set commit message language
+codexspec config --set-interaction-lang zh-CN
+codexspec config --set-document-lang en
 codexspec config --set-commit-lang en
 ```
 
@@ -680,8 +703,10 @@ codexspec config --set-commit-lang en
 version: "1.0"
 
 language:
-  output: "zh-CN"        # Output language
-  commit: "zh-CN"        # Commit message language (defaults to output)
+  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:

{codexspec-0.6.2 → codexspec-0.6.4}/README.md

@@ -483,12 +483,15 @@ Implementation follows **conditional TDD workflow**:
 
 | Option          | Description                           |
 | --------------- | ------------------------------------- |
-| `PROJECT_NAME`  | Project directory name                |
-| `--here`, `-h`  | Initialize in current directory       |
+| `PROJECT_NAME`  | Project directory name (`.` or `--here` for current dir) |
+| `--here`, `-h`  | Initialize in the current directory   |
 | `--ai`, `-a`    | AI assistant to use (default: claude) |
-| `--lang`, `-l`  | Output language (e.g., en, zh-CN, ja) |
-| `--force`, `-f` | Force overwrite existing files        |
-| `--no-git`      | Skip git initialization               |
+| `--lang`, `-l`  | Output (base) language; interaction/document/commit fall back to it (e.g., en, zh-CN, ja) |
+| `--interaction-lang` | Interaction language (LLM dialogue + CLI output); overrides `--lang` |
+| `--document-lang` | Document language (generated spec/plan/tasks); overrides `--lang` |
+| `--commit-lang` | Commit-message language; overrides `--lang` |
+| `--force`, `-f` | Overwrite files + auto-confirm prompts; never regenerates `config.yml` |
+| `--no-git`      | Skip git repository initialization    |
 | `--debug`, `-d` | Enable debug output                   |
 
 </details>
@@ -498,8 +501,10 @@ Implementation follows **conditional TDD workflow**:
 
 | Option                    | Description                  |
 | ------------------------- | ---------------------------- |
-| `--set-lang`, `-l`        | Set output language          |
-| `--set-commit-lang`, `-c` | Set commit message language  |
+| `--set-lang`, `-l`        | Set the output (base) language |
+| `--set-interaction-lang`  | Set the interaction language |
+| `--set-document-lang`     | Set the document language    |
+| `--set-commit-lang`, `-c` | Set the commit-message language |
 | `--list-langs`            | List all supported languages |
 
 </details>
@@ -583,28 +588,46 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 
 CodexSpec supports multiple languages through **LLM dynamic translation**. No translation templates to maintain - Claude translates content at runtime based on your language configuration.
 
+### 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 — so you can converse with Claude in one language while keeping generated artifacts or commit messages in another.
+
+| 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` | — | — | template source (always `en`) | — |
+
 ### Setting Language
 
 **During initialization:**
 
 ```bash
-# Create Chinese output project
+# Chinese output (sets the output base)
 codexspec init my-project --lang zh-CN
 
-# Create Japanese output project
-codexspec init my-project --lang ja
+# 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:**
 
 ```bash
 # View current configuration
 codexspec config
 
-# Change output language
+# Change a single dimension
 codexspec config --set-lang zh-CN
-
-# Set commit message language
+codexspec config --set-interaction-lang zh-CN
+codexspec config --set-document-lang en
 codexspec config --set-commit-lang en
 ```
 
@@ -635,8 +658,10 @@ codexspec config --set-commit-lang en
 version: "1.0"
 
 language:
-  output: "zh-CN"        # Output language
-  commit: "zh-CN"        # Commit message language (defaults to output)
+  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:

{codexspec-0.6.2 → codexspec-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.6.2"
+version = "0.6.4"
 description = "CodexSpec - A Requirements-First SDD toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

{codexspec-0.6.2 → codexspec-0.6.4}/src/codexspec/__init__.py

@@ -26,20 +26,19 @@ from .commands.installer import (
     install_commands_to_subdir,
     migrate_old_commands,
     should_update_commands,
+    update_installed_command_frontmatter,
 )
 from .i18n import (
     generate_config_content,
-    get_commit_language,
+    get_explicit_language_key,
     get_interaction_language,
     get_language_name,
     get_supported_languages,
     is_supported_language,
     normalize_locale,
-    update_config_language,
     update_language_field,
-    update_output_language,
 )
-from .translator import translate
+from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
 __version__ = "0.6.0"
@@ -273,6 +272,7 @@ def config(
         else:
             console.print("[red]Failed to update language setting[/red]")
             raise typer.Exit(1)
+        _rerender_command_frontmatter(config_file)
         return
 
     # Handle set commit language
@@ -351,6 +351,7 @@ def config(
         else:
             console.print("[red]Failed to update interaction language setting[/red]")
             raise typer.Exit(1)
+        _rerender_command_frontmatter(config_file)
         return
 
     # Handle set document language
@@ -445,13 +446,35 @@ def init(
         None,
         "--lang",
         "-l",
-        help="Output language (e.g., en, zh-CN, ja). Interactive prompt if not specified in TTY.",
+        help=(
+            "Output (base) language (e.g., en, zh-CN, ja). interaction/document/commit "
+            "fall back to it. Prompted on first-time init if not given in a TTY."
+        ),
+    ),
+    interaction_lang: Optional[str] = typer.Option(
+        None,
+        "--interaction-lang",
+        help=("Interaction language (LLM dialogue + codexspec CLI output); overrides --lang for this dimension."),
+    ),
+    document_lang: Optional[str] = typer.Option(
+        None,
+        "--document-lang",
+        help="Document language (generated requirements/spec/plan/tasks); overrides --lang.",
+    ),
+    commit_lang: Optional[str] = typer.Option(
+        None,
+        "--commit-lang",
+        help="Commit-message language; overrides --lang.",
     ),
     force: bool = typer.Option(
         False,
         "--force",
         "-f",
-        help="Force merge/overwrite when initializing in current directory",
+        help=(
+            "Overwrite existing files and auto-confirm prompts (skips the language "
+            "prompt and command-update/migration confirms). Language config is updated "
+            "surgically, never fully regenerated."
+        ),
     ),
     no_git: bool = typer.Option(
         False,
@@ -478,37 +501,104 @@ def init(
         codexspec init . --ai claude
         codexspec init --here --ai claude
         codexspec init . --force --ai claude
+        codexspec init my-project --interaction-lang en --document-lang zh-CN --commit-lang en
     """
-    # Handle interactive language selection when --lang not specified
-    if lang is None:
-        if sys.stdin.isatty():
-            # TTY environment: show interactive prompt
-            try:
-                lang = prompt_language_selection()
-            except KeyboardInterrupt:
-                console.print()
-                console.print("[yellow]Selection cancelled, using default language (en)[/yellow]")
-                lang = "en"
-        else:
-            # Non-TTY environment: use default
-            lang = "en"
-
-    # Normalize language code early for use throughout the function
-    normalized_lang = normalize_locale(lang)
-
-    # Determine target directory
+    # When init() is invoked directly (not via the Typer CLI), typer.Option defaults
+    # arrive as OptionInfo sentinels rather than None. Coerce the language params to
+    # Optional[str] so the resolution logic below is robust in both call paths.
+    lang = lang if isinstance(lang, str) else None
+    interaction_lang = interaction_lang if isinstance(interaction_lang, str) else None
+    document_lang = document_lang if isinstance(document_lang, str) else None
+    commit_lang = commit_lang if isinstance(commit_lang, str) else None
+
+    # Determine target directory first — needed to detect an existing config.yml
+    # before resolving the language base (REQ-007).
     if here or project_name == ".":
         target_dir = Path.cwd()
     elif project_name:
         target_dir = Path.cwd() / project_name
     else:
-        console.print(f"[red]{translate('cli.init.error_no_project_name', normalized_lang)}[/red]")
+        console.print(f"[red]{translate('cli.init.error_no_project_name', 'en')}[/red]")
         raise typer.Exit(1)
 
+    config_file = target_dir / ".codexspec" / "config.yml"
+    config_exists = config_file.exists()
+
+    def _normalize_lang_option(raw: str) -> str:
+        """Normalize a language flag value; warn (do not error) if unsupported."""
+        normalized = normalize_locale(raw)
+        if not is_supported_language(normalized):
+            console.print(f"[yellow]Warning: '{raw}' is not in the list of commonly supported languages.[/yellow]")
+            console.print(
+                "It may still work if Claude supports it. "
+                "Run [cyan]codexspec config --list-langs[/cyan] to see supported languages."
+            )
+        return normalized
+
+    # Per-dimension overrides: each flag maps to exactly one config key, with no
+    # CLI-level precedence between them (DEC-001).
+    lang_overrides: dict[str, str] = {}
+    if interaction_lang is not None:
+        lang_overrides["interaction"] = _normalize_lang_option(interaction_lang)
+    if document_lang is not None:
+        lang_overrides["document"] = _normalize_lang_option(document_lang)
+    if commit_lang is not None:
+        lang_overrides["commit"] = _normalize_lang_option(commit_lang)
+
+    # The output base is determinable if --lang was given OR all three specific
+    # dimensions are explicit (output is then irrelevant). Otherwise it must be
+    # prompted (first-time, TTY) or defaulted (first-time, non-TTY); on an
+    # existing config with no flag, everything is preserved (REQ-007).
+    output_value: Optional[str] = None
+    if lang is not None:
+        output_value = _normalize_lang_option(lang)
+    base_determinable = output_value is not None or (
+        "interaction" in lang_overrides and "document" in lang_overrides and "commit" in lang_overrides
+    )
+    prompted_base = False
+    if base_determinable:
+        # Output base already resolved (or None when only dimension flags were
+        # given); no prompt needed to resolve it.
+        pass
+    elif config_exists:
+        # Existing project: preserve every unspecified key (REQ-007); no prompt.
+        pass
+    elif sys.stdin.isatty():
+        try:
+            output_value = normalize_locale(prompt_language_selection())
+            prompted_base = True
+        except KeyboardInterrupt:
+            console.print()
+            console.print("[yellow]Selection cancelled, using default language (en)[/yellow]")
+            output_value = "en"
+    else:
+        output_value = "en"
+
+    # Render/CLI-message language = the effective interaction language for THIS
+    # run (frontmatter descriptions are an interaction-language artifact). This is
+    # deliberately decoupled from output_value/prompted_base above, which only
+    # drive config writing and the first-time prompt. Precedence: explicit
+    # --interaction-lang -> explicitly-configured interaction -> --lang (output
+    # base) -> explicitly-configured output -> "en". Existing interaction is
+    # deliberately stronger than --lang; existing output is only a fallback when
+    # this run did not provide a new base.
+    if "interaction" in lang_overrides:
+        normalized_lang = lang_overrides["interaction"]
+    elif config_exists and (explicit_interaction := get_explicit_language_key(config_file, "interaction")) is not None:
+        normalized_lang = explicit_interaction
+    elif output_value is not None:
+        normalized_lang = output_value
+    elif config_exists and (explicit_output := get_explicit_language_key(config_file, "output")) is not None:
+        normalized_lang = explicit_output
+    else:
+        normalized_lang = "en"
+
     if debug:
         console.print(f"[dim]Target directory: {target_dir}[/dim]")
         console.print(f"[dim]AI assistant: {ai}[/dim]")
-        console.print(f"[dim]Language: {lang} (normalized: {normalized_lang})[/dim]")
+        console.print(
+            f"[dim]Language base: {output_value} (messages: {normalized_lang}); overrides: {lang_overrides}[/dim]"
+        )
 
     # Check if directory exists and handle accordingly
     if target_dir.exists() and not here and project_name != ".":
@@ -591,7 +681,7 @@ def init(
         console.print(f"[dim]{translate('cli.init.migration_old_structure', normalized_lang)}[/dim]")
         console.print(f"[dim]{translate('cli.init.migration_new_structure', normalized_lang)}[/dim]")
 
-        if Confirm.ask(translate("cli.init.migration_confirm", normalized_lang), default=True):
+        if force or Confirm.ask(translate("cli.init.migration_confirm", normalized_lang), default=True):
             if migrate_old_commands(claude_dir, old_files):
                 console.print(f"[green]{translate('cli.init.migration_complete', normalized_lang)}[/green]")
                 migration_happened = True
@@ -603,14 +693,14 @@ def init(
     # Install or update commands (translate after migration if user wants)
     if migration_happened:
         # Migration moved files, ask if user wants to update/translate them
-        if Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
+        if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
             count = install_commands_to_subdir(
                 codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
             )
             console.print(f"[green]{translate('cli.init.commands_updated', normalized_lang, count=count)}[/green]")
     elif should_update_commands(codexspec_dir):
         console.print()
-        if Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
+        if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
             count = install_commands_to_subdir(
                 codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
             )
@@ -636,53 +726,50 @@ def init(
         msg = translate("cli.init.created_file", normalized_lang, file=".codexspec/memory/constitution.md")
         console.print(f"[green]{msg}[/green]")
 
-    # Create config.yml with language settings
+    # Apply language settings surgically (DEC-001 / CON-005 / REQ-005 / REQ-010).
+    # Build the full {key: value} map to write: the output base (if resolved) plus
+    # the per-dimension overrides. config.yml is never fully regenerated -- not
+    # even under --force -- and keys the user did not specify are always preserved.
     config_file = codexspec_dir / "config.yml"
-    if not config_file.exists() or force:
-        config_content = generate_config_content(
-            language=normalized_lang,
-            created=datetime.now().strftime("%Y-%m-%d"),
-        )
-        config_file.write_text(config_content, encoding="utf-8")
-        lang_name = get_language_name(normalized_lang)
-        msg = translate(
-            "cli.init.created_file",
-            normalized_lang,
-            file=f".codexspec/config.yml (language: {lang_name})",
-        )
-        console.print(f"[green]{msg}[/green]")
-    elif lang != "en":  # User explicitly provided --lang (not default)
-        # Check if commit language differs from selected language
-        current_commit_lang = get_commit_language(config_file)
-        if current_commit_lang and current_commit_lang != normalized_lang:
-            # Prompt user to update commit language
+    keys_to_write: dict[str, str] = {}
+    if output_value is not None:
+        keys_to_write["output"] = output_value
+    keys_to_write.update(lang_overrides)
+
+    wrote_keys: list[str] = []
+    if keys_to_write:
+        if not config_exists:
+            # Fresh project: emit only the chosen keys (sparse config).
+            config_content = generate_config_content(
+                output=keys_to_write.get("output"),
+                interaction=keys_to_write.get("interaction"),
+                document=keys_to_write.get("document"),
+                commit=keys_to_write.get("commit"),
+                created=datetime.now().strftime("%Y-%m-%d"),
+            )
+            config_file.write_text(config_content, encoding="utf-8")
+            wrote_keys = list(keys_to_write.keys())
+            lang_name = get_language_name(normalized_lang)
             msg = translate(
-                "cli.init.commit_lang_differs",
+                "cli.init.created_file",
                 normalized_lang,
-                current=current_commit_lang,
-                selected=normalized_lang,
+                file=f".codexspec/config.yml (language: {lang_name})",
             )
-            if Confirm.ask(msg, default=True):
-                update_config_language(config_file, normalized_lang)
-                console.print(
-                    f"[green]{translate('cli.init.commit_lang_updated', normalized_lang, lang=normalized_lang)}[/green]"
-                )
-            else:
-                # Update only output language, keep commit language
-                update_output_language(config_file, normalized_lang)
-                console.print(
-                    f"[dim]{translate('cli.init.commit_lang_kept', normalized_lang, lang=current_commit_lang)}[/dim]"
-                )
+            console.print(f"[green]{msg}[/green]")
         else:
-            # No difference or commit lang not set, update both
-            if update_config_language(config_file, normalized_lang):
-                lang_name = get_language_name(normalized_lang)
-                msg = translate(
-                    "cli.init.language_updated",
-                    normalized_lang,
-                    lang_name=lang_name,
-                )
-                console.print(f"[green]{msg}[/green]")
+            # Existing project: update each chosen key in place, preserving the rest.
+            for key, value in keys_to_write.items():
+                if update_language_field(config_file, key, value):
+                    wrote_keys.append(key)
+
+    # Non-blocking notice of which language keys were set (REQ-010).
+    if wrote_keys:
+        details = ", ".join(f"{k}={keys_to_write[k]}" for k in wrote_keys)
+        console.print(f"[dim]{translate('cli.init.language_key_set', normalized_lang, details=details)}[/dim]")
+
+    # Discoverability hint after a first-time interactive base selection (REQ-009).
+    if prompted_base:
+        console.print(f"[dim]{translate('cli.init.language_dimensions_hint', normalized_lang)}[/dim]")
 
     # Create CLAUDE.md
     claude_md = target_dir / "CLAUDE.md"
@@ -738,6 +825,29 @@ def init(
     console.print(f"[yellow]{translate('cli.init.important_action', normalized_lang)}[/yellow]")
 
 
+def _rerender_command_frontmatter(config_file: Path) -> None:
+    """Re-render installed command frontmatter in the current interaction language.
+
+    Called after a ``config`` language change so ``.claude/commands/codexspec/*.md``
+    descriptions follow the new interaction language immediately, mirroring what
+    ``init`` does. No-op when commands are not installed. Languages without a
+    pre-translated cache are not re-rendered here (that path would invoke the
+    ``claude`` CLI once per command); the user is advised to run ``codexspec init``.
+    """
+    commands_subdir = Path.cwd() / ".claude" / "commands" / COMMANDS_SUBDIR
+    if not commands_subdir.exists():
+        return
+    language = get_interaction_language(config_file)  # re-read AFTER the config write
+    if language != "en" and language not in SUPPORTED_LANGUAGES:
+        console.print(f"[dim]Run [cyan]codexspec init[/cyan] to update command descriptions for {language}.[/dim]")
+        return
+    templates_dir = get_templates_dir() / "commands"
+    if not templates_dir.exists():
+        return
+    update_installed_command_frontmatter(commands_subdir, templates_dir, language=language)
+    console.print(f"[dim]Updated command descriptions to: {get_language_name(language)}[/dim]")
+
+
 def _print_command_summary(language: str = "en") -> None:
     """Print a summary of installed commands grouped by category."""
     metadata = get_commands_metadata()

{codexspec-0.6.2 → codexspec-0.6.4}/src/codexspec/commands/installer.py

@@ -8,7 +8,12 @@ import shutil
 from pathlib import Path
 from typing import Optional, TypedDict
 
-from codexspec.translator import extract_frontmatter_fields, load_translation_cache, translate_template_frontmatter
+from codexspec.translator import (
+    apply_translations_to_template,
+    extract_frontmatter_fields,
+    load_translation_cache,
+    translate_template_frontmatter,
+)
 
 # Constants
 COMMANDS_SUBDIR = "codexspec"  # Subdirectory name for commands
@@ -348,6 +353,49 @@ def install_commands_to_subdir(
     return installed_count
 
 
+def update_installed_command_frontmatter(
+    target_dir: Path,
+    templates_dir: Path,
+    language: str = "en",
+    translations_dir: Optional[Path] = None,
+) -> int:
+    """Update frontmatter translations for already-installed command files.
+
+    This preserves command bodies and any non-translated frontmatter while
+    refreshing the language-specific ``description`` and ``argument-hint`` fields.
+    Missing installed commands are intentionally skipped.
+    """
+    if not target_dir.exists() or not templates_dir.exists():
+        return 0
+
+    translation_cache = None
+    if language != "en":
+        translation_cache = load_translation_cache(language, translations_dir)
+
+    updated_count = 0
+    for template_file in templates_dir.glob("*.md"):
+        target_path = target_dir / template_file.name
+        if not target_path.exists():
+            continue
+
+        template_content = template_file.read_text(encoding="utf-8")
+        template_name = template_file.stem
+        rendered_template = translate_template_frontmatter(template_content, template_name, language, translation_cache)
+        fields = {
+            key: value for key, value in extract_frontmatter_fields(rendered_template).items() if value is not None
+        }
+        if not fields:
+            continue
+
+        current_content = target_path.read_text(encoding="utf-8")
+        updated_content = apply_translations_to_template(current_content, fields)
+        if updated_content != current_content:
+            target_path.write_text(updated_content, encoding="utf-8")
+            updated_count += 1
+
+    return updated_count
+
+
 def should_update_commands(codexspec_dir: Path) -> bool:
     """Check if commands need updating (subdirectory already exists).