# CR-002: Settings Language Switch (Web UI)

## Change Request Details

| Field | Value |
|-------|-------|
| CR ID | CR-002 |
| Feature | FEATURE-028 (new sub-feature: FEATURE-028-D) |
| Requestor | Human |
| Date | 2026-02-11 |
| Priority | Medium |
| Classification | Modification (new sub-feature within FEATURE-028) |
| Source | [IDEA-020](../../ideas/016.%20CR-Switch%20Language%20in%20Settings/idea-summary-v1.md) |

## Description

Add a language dropdown (en / 中文) to the Settings web UI page, enabling users to switch the project's language without using the CLI. The switch replicates `x-ipe upgrade --lang zh|en` behavior — updating `.x-ipe.yaml` and re-extracting copilot instructions for the selected language automatically.

## Business Justification

Language switching is currently CLI-only (`x-ipe upgrade --lang`). Users who interact primarily through the web UI must drop to the terminal for a simple preference change. The Settings page — the natural home for project configuration — should expose this option.

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-028 — New sub-feature FEATURE-028-D

**Reasoning:**
- Works within the existing FEATURE-028 bilingual system (same `.x-ipe.yaml` language field, same ScaffoldManager logic)
- Same users, same data model, extended access channel (web UI in addition to CLI)
- Requires a **new API endpoint** (`POST /api/config/language`) and **new UI elements** (Settings page language section), which warrants a separate sub-feature rather than modifying an existing one
- Does not change the fundamental scope of FEATURE-028 — it extends the *access method* for an existing capability

### Comparison Matrix

| Aspect | CR Requirement | Existing FEATURE-028 |
|--------|---------------|---------------------|
| Users | Same web UI users | CLI + web UI users |
| Workflow | Settings page → dropdown → API → ScaffoldManager | CLI → `--lang` flag → ScaffoldManager |
| Data Model | Same `.x-ipe.yaml` `language` field | Same |
| UI Elements | **New**: Language section in Settings page, confirmation dialog | None in Settings |
| API Endpoints | **New**: `POST /api/config/language` | Existing: `GET /api/config` |

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| `settings.html` | High | New Language section with dropdown, confirmation dialog |
| `settings_routes.py` | High | New `POST /api/config/language` endpoint |
| `scaffold.py` (ScaffoldManager) | Low | Already has the logic; called from new route |
| `.x-ipe.yaml` | None | Same `language` field, no schema change |

### Dependencies

- FEATURE-028-A: v3.0 schema (foundation)
- FEATURE-028-B: ScaffoldManager language switch logic (reused)
- FEATURE-028-C: Frontend language awareness (complementary)

## Proposed Approach

Create FEATURE-028-D as a new sub-feature of FEATURE-028:
1. **New API endpoint** `POST /api/config/language` in `settings_routes.py`
2. **Settings page UI** — dedicated Language section with dropdown, confirmation dialog, toast
3. **Backend reuse** — call existing ScaffoldManager methods (same as CLI `_handle_language_switch`)
4. **Atomicity** — extract instructions first, then update config (rollback-safe)

## Mockup Impact

**UI/UX Change:** Yes
**Existing Mockups Referenced:** None (Settings page had no prior mockups)

**New Mockup(s):**

| New Mockup | Path | Changes Applied |
|------------|------|-----------------|
| Settings Language Switch v1 | [mockups/settings-language-v1.html](../../ideas/016.%20CR-Switch%20Language%20in%20Settings/mockups/settings-language-v1.html) | 4 interactive scenarios: default state, confirmation dialog, success toast, same-language guard |

## Acceptance Criteria

- AC-CR2-1: Settings page MUST display a dedicated "Language" section above Project Folders
- AC-CR2-2: Language section MUST show current language with a badge and dropdown select (en / 中文)
- AC-CR2-3: Selecting a different language MUST show a confirmation dialog warning about instruction regeneration
- AC-CR2-4: Confirming MUST call `POST /api/config/language` with `{ "language": "zh|en" }`
- AC-CR2-5: Backend MUST extract instructions FIRST, then update `.x-ipe.yaml` (atomicity)
- AC-CR2-6: On success, MUST show a toast notification without page reload (AJAX)
- AC-CR2-7: Selecting the same language MUST be a no-op with informational toast
- AC-CR2-8: Dropdown MUST be disabled during the switch operation (prevent double-submit)
- AC-CR2-9: Custom edits outside X-IPE markers in copilot-instructions MUST be preserved

## Approval

- [x] Classification approved by human (auto_proceed=true)
- [x] Approach approved by human
- [x] Ready for execution

## Execution

**Classification Result:** modification (new sub-feature FEATURE-028-D)

**Actions Taken:**
- [x] CR document created (this file) — stored in FEATURE-028-D folder
- [x] Requirement-details-part-6.md updated with FEATURE-028-D entry
- [x] Features board updated with FEATURE-028-D row
- [x] Mockup referenced from idea folder
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Idea Summary: [idea-summary-v1.md](../../ideas/016.%20CR-Switch%20Language%20in%20Settings/idea-summary-v1.md)
- Mockup: [settings-language-v1.html](../../ideas/016.%20CR-Switch%20Language%20in%20Settings/mockups/settings-language-v1.html)
- Requirement Details: [requirement-details-part-6.md](../requirement-details-part-6.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-02-11 | CR-002 created | Sage |
