goodgo-platform/docs/architecture/IMPLEMENTATION_QUICK_REFERENCE.md

GoodGo Frontend: Tham chiếu nhanh triển khai i18n + A11y

🎯 Những phát hiện chính trong nháy mắt

Trạng thái hiện tại

• ✅ Next.js 15 với App Router (cấu trúc tốt)
• ✅ React 18 + TypeScript (an toàn kiểu)
• ✅ Tailwind CSS với hỗ trợ dark mode (theme dựa trên HSL)
• ✅ Thư viện component tốt (~35 component)
• ✅ Một số kiến thức cơ bản về A11y đã có (HTML ngữ nghĩa, ARIA labels, skip link)
• ❌ CHƯA thiết lập i18n (tất cả tiếng Việt được hardcode)
• ❌ Thiếu sót A11y (quản lý focus, một số ARIA còn thiếu, tương phản màu chưa xác định)

Điểm vào chiến lược cho việc triển khai

1. Điểm vào i18n (Ưu tiên 1)

Files to modify for i18n:
├── app/layout.tsx                    → Add i18n provider
├── middleware.ts                     → Add locale routing
├── app/(public)/layout.tsx           → Navigation text
├── app/(auth)/login/page.tsx         → Form labels + errors
├── app/(auth)/register/page.tsx      → Form labels + errors
├── components/listings/listing-form-steps.tsx → Multi-step form labels
├── components/search/filter-bar.tsx  → Filter options + city names
├── lib/validations/*.ts             → Zod error messages
└── [All other components with text]

Total files to update: ~25-30 files with hardcoded strings

2. Sửa lỗi A11y quan trọng (Ưu tiên 1.5)

Components needing A11y updates:
├── components/ui/dialog.tsx         → Focus trapping + focus restoration
├── components/listings/image-gallery.tsx → Keyboard nav + ARIA
├── components/search/filter-bar.tsx  → Proper labeling + ARIA
├── app/(dashboard)/layout.tsx        → Tab focus management
└── Across all forms                 → Error message association

Tasks:
- Add focus trapping in modals
- Verify color contrast (WCAG AA)
- Add aria-busy to loading states
- Add proper aria-label to icon buttons
- Link form errors to inputs with aria-describedby

3. Cấu trúc file Message cho i18n

public/locales/
├── en.json
│   ├── common: { home, search, dashboard, logout, ... }
│   ├── auth: { login, register, email, password, ... }
│   ├── property: { apartment, house, villa, ... }
│   ├── transaction: { sale, rent, ... }
│   ├── directions: { north, south, east, ... }
│   ├── status: { draft, active, sold, ... }
│   ├── validation: { required, min_length, ... }
│   └── errors: { oauth_failed, access_denied, ... }
└── vi.json
    └── [Same structure]

---

📋 Checklist triển khai

Giai đoạn 1: Thiết lập (2-3 giờ)

• Cài đặt gói next-intl
• Tạo các file message (en.json, vi.json)
• Cập nhật next.config.js cho routing i18n
• Tạo cấu hình i18n (config.ts)
• Cập nhật middleware.ts để phát hiện locale
• Bao bọc root layout bằng provider i18n

Giai đoạn 2: Tái cấu trúc cốt lõi (6-8 giờ)

• Cập nhật root layout & metadata
• Tái cấu trúc tất cả validation (Zod) để sử dụng messages
• Trích xuất chuỗi component sang useTranslations()
• Cập nhật tất cả các enum (TRANSACTION_TYPES, PROPERTY_TYPES, v.v.) để sử dụng i18n
• Cập nhật các page layout (public, auth, dashboard)
• Cập nhật toàn bộ nội dung trang

Giai đoạn 3: Cập nhật component (4-6 giờ)

• Cập nhật tất cả các component UI
• Cập nhật các component form
• Cập nhật các component navigation
• Cập nhật các component search/filter
• Cập nhật form đăng tin (listing form)

Giai đoạn 4: Sửa lỗi A11y (4-6 giờ)

• Sửa quản lý focus trong dialog
• Thêm focus trapping
• Cập nhật liên kết lỗi form (aria-describedby)
• Thêm aria-busy cho trạng thái loading
• Thêm aria-label cho các nút biểu tượng
• Xác minh tương phản màu
• Cập nhật thiết lập test cho i18n

Giai đoạn 5: Test & QA (3-4 giờ)

• Test cả hai locale trên tất cả các trang
• Chạy kiểm tra khả năng tiếp cận bằng axe DevTools
• Test điều hướng bằng bàn phím
• Test tương thích screen reader
• Cập nhật unit test cho i18n

---

🗣️ Kiểm kê nội dung văn bản

Navigation & Layout (~15 mục)

Vị trí	Văn bản	Trạng thái
Public header	Trang chủ, Tìm kiếm, Đăng nhập, Đăng ký	❌ Hardcoded
Dashboard nav	8 mục nav	❌ Hardcoded
Footer	4 phần	❌ Hardcoded

Forms & Validation (~40+ mục)

Vị trí	Loại	Số lượng	Trạng thái
Login form	Nhãn + lỗi	8	❌ Hardcoded
Register form	Nhãn + lỗi	10	❌ Hardcoded
Listing form	Nhãn đa bước	25+	❌ Hardcoded
Search filters	Nhãn tùy chọn	30+	❌ Hardcoded
Zod validation	Thông báo lỗi	20+	❌ Hardcoded

Enum & Hằng số (~50+ mục)

File	Mục	Trạng thái
TRANSACTION_TYPES	2 nhãn	❌ Hardcoded
PROPERTY_TYPES	6 nhãn	❌ Hardcoded
LISTING_STATUSES	8 nhãn	❌ Hardcoded
DIRECTIONS	8 nhãn	❌ Hardcoded
CITIES	13 tên	❌ Hardcoded
PRICE_RANGES	6 khoảng	❌ Hardcoded

Nội dung trang (~30 mục)

Trang	Phần	Trạng thái
Trang landing	Hero, search, stats, CTA	❌ Hardcoded
Kết quả tìm kiếm	Không có kết quả, loading, header	❌ Hardcoded
Dashboard	Tiêu đề phần, trạng thái rỗng	❌ Hardcoded

---

🔑 Các file quan trọng cho i18n

Các file phải cập nhật (Blocker)

1. middleware.ts — Định tuyến locale
2. app/layout.tsx — Thiết lập provider i18n
3. lib/validations/*.ts — Tích hợp messages
4. lib/*.ts — Bất kỳ xử lý thông báo lỗi API nào

Các file ưu tiên cao

1. app/(public)/layout.tsx — Navigation
2. app/(auth)/login/page.tsx — Form xác thực
3. components/listings/listing-form-steps.tsx — Forms
4. components/search/filter-bar.tsx — Bộ lọc

Các file ưu tiên trung bình

1. Tất cả các component trang
2. Tất cả các component UI có văn bản
3. Các component error boundary

---

♿ Ưu tiên triển khai A11y

Sửa lỗi quan trọng WCAG 2.1 AA

1. Quản lý focus (Cấp A)

   • Thêm focus trap trong dialog.tsx
   • Khôi phục focus khi đóng dialog
   • Chỉ báo focus rõ ràng trên tất cả các nút

2. Tương phản màu (Cấp AA)

   • Chạy kiểm tra axe DevTools
   • Sửa văn bản có tỷ lệ < 4.5:1
   • Sửa đồ họa có tỷ lệ < 3:1

3. Khả năng tiếp cận form (Cấp A)

   • Liên kết tất cả thông báo lỗi với aria-describedby
   • Gắn nhãn đúng cách với htmlFor
   • Nhóm fieldset cho các form phức tạp

4. Trạng thái Loading (Cấp A)

   • Thêm aria-busy cho spinner
   • Thêm aria-label kèm ngữ cảnh

5. Nút biểu tượng (Cấp A)

   • Tất cả các nút chỉ có biểu tượng cần aria-label
   • Nút bật/tắt theme đã có nhãn ✓

Các cải tiến A11y nên có

• Skip link đã có sẵn ✓
• HTML ngữ nghĩa đã được sử dụng ✓
• Role="alert" trên lỗi ✓
• aria-invalid trên các trường form ✓

---

📦 Các phụ thuộc cần thêm

npm install next-intl

# No new devDependencies needed if using next-intl
# Testing with mocked i18n available

Tổng kích thước cài đặt: ~500KB đã minify

---

🧪 Chiến lược test

Unit Tests

// vitest.setup.ts - Mock i18n
vi.mock('next-intl', () => ({
  useTranslations: () => (key) => mockMessages[key]
}));

Component Tests

// Test both locales
describe('LoginForm', () => {
  it('renders Vietnamese labels', () => { ... });
  it('renders English labels', () => { ... });
});

E2E Tests

// Test locale switching
- /en/login → English
- /vi/login → Vietnamese
- /en/dashboard → English dashboard

---

📊 Lộ trình ước tính

Giai đoạn	Thời gian	Công sức
Thiết lập	2-3h	Thấp
Tái cấu trúc cốt lõi	6-8h	Trung bình
Components	4-6h	Trung bình
Sửa lỗi A11y	4-6h	Thấp-Trung bình
Testing	3-4h	Trung bình
Tổng	19-27h	~3-4 ngày

---

🚀 Thứ tự triển khai (Khuyến nghị)

1. Thiết lập hạ tầng i18n (tạo nền tảng)
2. Cập nhật middleware + root layout (kích hoạt routing)
3. Trích xuất & tập trung tất cả văn bản (công việc chính)
4. Sửa các vấn đề A11y (song song với #3)
5. Test kỹ lưỡng (xác minh cuối cùng)

---

💡 Cơ hội thắng nhanh

Những việc có thể làm ngay:

1. Tạo cấu trúc file message (30 phút)
2. Thêm focus trap cho dialog (30 phút)
3. Thêm aria-busy cho spinner (20 phút)
4. Kiểm tra tương phản màu (1 giờ)
5. Aria-label cho nút biểu tượng (30 phút)

---

📝 Ghi chú khi triển khai

Phát hiện locale (middleware)

// Check in order: URL > cookie > header > default
function getLocale(request) {
  // 1. URL pathname: /en/* or /vi/*
  // 2. Cookie: goodgo_locale
  // 3. Header: Accept-Language
  // 4. Default: vi
}

Chiến lược dự phòng Message

// If translation missing, use English as fallback
// Otherwise fallback to Vietnamese (primary)

Cân nhắc về hiệu năng

• Giữ các file message < 100KB mỗi file
• Lazy load message theo trang nếu cần
• Static generation cho các trang quan trọng về SEO

---

Cập nhật lần cuối: Ngày 9 tháng 4 năm 2026
Phiên bản: 1.0 - Trước triển khai
Độ tin cậy: Cao