claudecodeui/openspec/changes/add-i18n-support/specs/user-interface/spec.md

# User Interface Capability Specification (Delta)

## ADDED Requirements

### Requirement: Language-Aware UI Components

All user-facing UI components SHALL support internationalization and display translated text based on user's language preference.

#### Scenario: Settings page displays translated labels
- **WHEN** user opens Settings page
- **THEN** all section labels (Account, Permissions, MCP Servers, Appearance) SHALL be translated
- **AND** button labels (Save, Cancel, Delete) SHALL be translated
- **AND** description text SHALL be translated
- **AND** technical terms (e.g., JWT, API, SSH) may remain in English if no common translation exists

#### Scenario: Sidebar displays translated navigation
- **WHEN** user views sidebar navigation
- **THEN** section headers (Projects, Sessions) SHALL be translated
- **AND** action buttons (New Project, Refresh, Settings) SHALL be translated
- **AND** status messages (Loading, Error) SHALL be translated

#### Scenario: Login form displays translated text
- **WHEN** user views login form
- **THEN** form labels (Username, Password) SHALL be translated
- **AND** button text (Sign In, Create Account) SHALL be translated
- **AND** validation messages (Invalid credentials, Required field) SHALL be translated
- **AND** error messages SHALL be translated

#### Scenario: File operations show translated prompts
- **WHEN** user performs file operations (Save, Delete, Rename)
- **THEN** confirmation dialogs SHALL be translated
- **AND** success messages SHALL be translated
- **AND** error messages SHALL be translated

### Requirement: Language Selector in Settings

The Settings > Account section SHALL provide a language selector dropdown allowing users to choose their preferred language.

#### Scenario: Language selector displays current language
- **WHEN** user navigates to Settings > Account
- **THEN** a language selector dropdown SHALL be visible
- **AND** display label: "Language" (or translated equivalent)
- **AND** show currently selected language as default value
- **AND** list available options: English, 简体中文

#### Scenario: Language selector updates preference
- **WHEN** user selects a different language from dropdown
- **THEN** the system SHALL immediately change application language
- **AND** show loading indicator if translations are being loaded
- **AND** refresh all UI components with new language
- **AND** save preference to localStorage
- **AND** display success message: "Language changed successfully"

#### Scenario: Language selector persists across sessions
- **WHEN** user returns to application after closing
- **THEN** the language selector SHALL display the previously selected language
- **AND** the application UI SHALL be in the selected language
- **AND** the selector SHALL not show "Language" as default if user previously chose Chinese

### Requirement: Responsive Layout for Translated Text

UI components SHALL accommodate varying text lengths across languages without breaking layout or readability.

#### Scenario: Chinese text fits in buttons
- **WHEN** UI is displayed in Chinese (which often has longer text than English)
- **THEN** buttons SHALL expand to fit translated text
- **AND** text SHALL NOT overflow or wrap awkwardly
- **AND** button heights SHALL remain consistent

#### Scenario: Mobile layout handles longer translations
- **WHEN** application is viewed on mobile device with Chinese language
- **THEN** navigation menus SHALL accommodate longer text labels
- **AND** sidebar items SHALL not truncate important text
- **AND** layout SHALL remain responsive and touch-friendly

#### Scenario: Tables and lists maintain alignment
- **WHEN** table headers or list items are translated
- **THEN** column widths SHALL adjust to fit translated content
- **AND** text alignment SHALL remain appropriate (left-to-right for both languages)
- **AND** content SHALL remain readable without horizontal scrolling

### Requirement: Error and Status Messages

All error messages, success notifications, and status indicators SHALL be translated to provide clear feedback in user's preferred language.

#### Scenario: Error messages are translated
- **WHEN** an error occurs (e.g., network failure, validation error)
- **THEN** error message SHALL be displayed in user's selected language
- **AND** technical error codes MAY remain in English
- **AND** suggestions for resolution SHALL be translated

#### Scenario: Success notifications are translated
- **WHEN** an operation completes successfully (e.g., file saved, settings updated)
- **THEN** success message SHALL be displayed in user's selected language
- **AND** action buttons in notification (e.g., "Dismiss") SHALL be translated

#### Scenario: Loading states are translated
- **WHEN** application shows loading indicator
- **THEN** loading text SHALL be in user's selected language (e.g., "Loading..." vs "加载中...")
- **AND** progress messages SHALL be translated

#### Scenario: Validation messages are translated
- **WHEN** user submits form with invalid data
- **THEN** validation error SHALL be in user's selected language
- **AND** field-specific hints SHALL be translated
- **AND** placeholder text SHALL be translated

### Requirement: Accessibility with Translations

Translated UI SHALL maintain accessibility standards including screen reader compatibility and keyboard navigation.

#### Scenario: Screen readers announce translated text
- **WHEN** screen reader user navigates UI
- **THEN** screen reader SHALL announce translated text correctly
- **AND** language attribute SHALL be set on HTML element: `<html lang="zh-CN">`
- **AND** dynamic language changes SHALL update lang attribute

#### Scenario: Keyboard navigation works with translated labels
- **WHEN** user navigates with keyboard
- **THEN** all interactive elements SHALL be accessible via Tab key
- **AND** focus indicators SHALL be visible regardless of text length
- **AND** keyboard shortcuts SHALL work consistently across languages

### Requirement: Date and Number Formatting

The system SHALL format dates, numbers, and other locale-specific data according to user's language preference.

#### Scenario: Dates are formatted for locale
- **WHEN** application displays dates (e.g., file modification time, session creation time)
- **THEN** dates SHALL be formatted according to locale conventions
- **AND** Chinese users see: 2025年1月16日
- **AND** English users see: January 16, 2025

#### Scenario: Numbers are formatted for locale
- **WHEN** application displays numbers (e.g., token usage, file sizes)
- **THEN** numbers SHALL use appropriate digit grouping symbols
- **AND** Chinese users see: 1,234 (comma separator)
- **AND** decimal separators match locale preference

#### Scenario: File sizes are human-readable
- **WHEN** application displays file sizes
- **THEN** sizes SHALL be formatted with appropriate units (KB, MB, GB)
- **AND** unit labels SHALL be translated (e.g., "KB" vs "千字节")
- **AND** formatting shall be consistent across languages

## MODIFIED Requirements

### Requirement: Settings Page Navigation

The Settings page SHALL provide tabs for Account, Permissions, MCP Servers, and Appearance settings. All tab labels, section headers, and descriptions SHALL be translated based on user's language preference. The Account tab SHALL include a language selector dropdown that allows users to choose between English and Simplified Chinese.

#### Scenario: Navigate Settings with translated labels
- **WHEN** user opens Settings page
- **THEN** all navigation elements SHALL be in user's selected language
- **AND** tab labels SHALL be translated (Account → 账户, Permissions → 权限)
- **AND** active tab SHALL be visually indicated
- **AND** language selector SHALL be visible in Account tab

### Requirement: Onboarding Flow

New users SHALL see onboarding wizard explaining application features. All onboarding text, instructions, and button labels SHALL be translated based on user's language preference. The wizard SHALL automatically detect user's system language when possible.

#### Scenario: Onboarding in selected language
- **WHEN** new user first launches application
- **THEN** onboarding wizard SHALL detect system language or default to English
- **AND** all wizard text SHALL be translated
- **AND** user may change language during onboarding via language selector
- **AND** language preference SHALL persist after onboarding completes

## REMOVED Requirements

*N/A - No requirements are removed, only enhanced with i18n support.*

## RENAMED Requirements

*N/A - No requirements are renamed.*