docs(i18n): add dashboard localization guide and links

docs/i18n-dashboard.md

@@ -0,0 +1,113 @@
+# Dashboard i18n Guide
+
+Last Updated: 2026-03-02
+
+This document describes the internationalization (i18n) architecture used by the CCS Dashboard (`ui/`), how locale selection works, and how to add new languages safely.
+
+---
+
+## Scope
+
+Dashboard i18n currently covers UI text rendered by React components.
+
+- Supported locales today:
+  - `en` (English)
+  - `zh-CN` (Simplified Chinese)
+- Locale state is persisted in browser localStorage using `ccs-ui-locale`.
+- Fallback language is `en`.
+
+Out of scope:
+
+- CLI terminal output localization
+- Backend/API payload localization
+
+---
+
+## Architecture
+
+### Initialization
+
+- File: `ui/src/App.tsx`
+- `import '@/lib/i18n'` initializes i18next once before routes render.
+
+### Translation resources
+
+- File: `ui/src/lib/i18n.ts`
+- Contains `resources` object with locale blocks:
+  - `en.translation`
+  - `zh-CN.translation`
+- Uses `initReactI18next` for React integration.
+
+### Locale utilities
+
+- File: `ui/src/lib/locales.ts`
+- Core helpers:
+  - `normalizeLocale(locale)` maps browser/storage values to supported app locales.
+  - `getInitialLocale` chooses stored locale, then browser locale, then `en`.
+  - `persistLocale` writes normalized locale to localStorage.
+
+### Language switcher
+
+- File: `ui/src/components/layout/language-switcher.tsx`
+- Uses `react-i18next` + shadcn `Select`.
+- Calls `persistLocale` and `i18n.changeLanguage` on selection.
+
+---
+
+## Key Conventions
+
+### Translation key naming
+
+Use dot-notation namespaces by feature area:
+
+- `nav.home`
+- `cursorPage.title`
+- `settingsTabs.web`
+
+Keep key names stable and semantic to minimize churn across locales.
+
+### Pluralization
+
+For count-based strings, use i18next suffix rules:
+
+- `<key>_one`
+- `<key>_other`
+
+Examples exist in sync/account counters.
+
+### Interpolation and rich text
+
+- Use interpolation for runtime values: `t('key', { value })`.
+- Prefer plain text keys whenever possible.
+- If formatting is required (for example bold segments), use `<Trans />` instead of `dangerouslySetInnerHTML`.
+
+---
+
+## Adding a New Locale
+
+When adding a locale such as Vietnamese (`vi`):
+
+1. Add locale id to the supported locale list in `ui/src/lib/locales.ts`.
+2. Add locale display label under `translation.locale` in `ui/src/lib/i18n.ts`.
+3. Add a full `<locale>.translation` block with all keys.
+4. Verify fallback behavior remains `en` for missing keys.
+5. Run UI validation and i18n tests:
+   - `cd ui && bun run validate`
+   - `cd ui && bun run test:run tests/unit/ui/i18n/language-switcher.test.tsx`
+6. Add or update key-parity tests to catch locale drift.
+
+Tracking issue for comprehensive Vietnamese locale:
+
+- https://github.com/kaitranntt/ccs/issues/659
+
+---
+
+## Contributor Checklist
+
+Before opening a PR that touches i18n:
+
+- [ ] New UI strings are translated in all supported locales.
+- [ ] No raw key literals appear in UI at runtime.
+- [ ] No unsafe HTML injection path introduced for translated content.
+- [ ] `ui` validate/test commands pass.
+- [ ] This document is updated if architecture or conventions changed.

docs/project-roadmap.md

@@ -86,6 +86,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 |-------|-------|------|
 | #137 | CCS Cannot Connect to IDE, but Native Claude Works | support |
 | #89 | Add Claude Code CLI flag passthrough for delegation | enhancement |
+| #659 | Comprehensive Vietnamese i18n for dashboard | enhancement |
 
 ### Low Priority / Questions
 

docs/system-architecture/index.md

@@ -1,6 +1,6 @@
 # CCS System Architecture
 
-Last Updated: 2026-02-16
+Last Updated: 2026-03-02
 
 High-level architecture overview for the CCS (Claude Code Switch) system.
 
@@ -15,6 +15,8 @@ The system consists of two main components:
 1. **CLI Application** (`src/`) - Node.js TypeScript CLI
 2. **Dashboard UI** (`ui/`) - React web application served by Express
 
+Dashboard localization (i18n) architecture and contributor workflow are documented in [Dashboard i18n Guide](../i18n-dashboard.md).
+
 CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy with automatic injection for all profile types.
 
 ```