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.