11f2bf26e6
11 KiB
Tài Liệu Frontend GoodGo - Triển Khai i18n & Accessibility
📚 Mục Lục Tài Liệu
Gói này chứa tài liệu toàn diện cho việc triển khai hỗ trợ i18n next-intl (Tiếng Việt + Tiếng Anh) và sửa lỗi accessibility theo WCAG 2.1 AA trong frontend Next.js của GoodGo Platform (apps/web).
📄 Các Tài Liệu Được Cung Cấp
1. EXPLORATION_SUMMARY.txt ⭐ BẮT ĐẦU TỪ ĐÂY
Đọc trong 15 phút | Tổng quan điều hành
Tóm tắt cấp cao về các phát hiện:
- Điểm mạnh và khoảng trống chính
- Tổng quan về tech stack
- Kiểm kê nội dung (200+ mục cần dịch)
- Các tệp quan trọng cần cập nhật
- Kết quả kiểm tra A11y
- Ước tính thời gian (19-27 giờ)
Phù hợp nhất cho: Quản lý dự án, các bên liên quan, tổng quan nhanh
2. docs/audits/FRONTEND_EXPLORATION.md 📋 TÀI LIỆU THAM KHẢO CHI TIẾT
Đọc trong 45 phút | Phân tích toàn diện
Phân tích cực kỳ chi tiết:
- Cấu trúc thư mục đầy đủ kèm mô tả
- Toàn bộ 90+ tệp được phân tích
- Phân tích chi tiết package.json
- Trạng thái hiện tại của root layout
- Logic định tuyến middleware
- Cấu hình Tailwind CSS
- Vị trí nội dung văn bản (hardcoded)
- Trạng thái accessibility hiện tại
- Cấu trúc dữ liệu & enum
- Thiết lập kiểm thử
Phù hợp nhất cho: Lập trình viên, kiến trúc sư, lập kế hoạch triển khai
3. IMPLEMENTATION_QUICK_REFERENCE.md 🚀 HƯỚNG DẪN KHỞI ĐẦU NHANH
Đọc trong 30 phút | Định hướng hành động
Hướng dẫn triển khai tập trung:
- Các phát hiện chính tổng quan
- Các điểm vào chiến lược (i18n, A11y, cấu trúc message)
- Danh sách kiểm tra triển khai 5 giai đoạn
- Kiểm kê nội dung văn bản theo loại
- Tệp ưu tiên Quan trọng / Cao / Trung bình
- Lộ trình ưu tiên A11y
- Chiến lược kiểm thử
- Yêu cầu về dependency
- Cơ hội thắng lợi nhanh
Phù hợp nhất cho: Trưởng nhóm kỹ thuật, lập kế hoạch sprint, phân chia công việc
4. FILE_MAPPING_GUIDE.md 🗂️ KẾ HOẠCH TRIỂN KHAI CHI TIẾT
Đọc trong 60 phút | Hướng dẫn từng tệp
Hướng dẫn cập nhật tệp theo từng giai đoạn:
- Giai đoạn 1: Hạ tầng (middleware, root layout, config)
- Giai đoạn 2: Cập nhật core component (layouts, pages)
- Giai đoạn 3: Cập nhật form & validation
- Giai đoạn 4: Cập nhật tiện ích & API
- Giai đoạn 5: Sửa lỗi accessibility
- Giai đoạn 6: Cập nhật thiết lập kiểm thử
Mỗi phần bao gồm:
- Trạng thái hiện tại
- Các thay đổi cần thực hiện
- Ví dụ code (pseudo-code)
- Đánh giá độ phức tạp cụ thể
- Hướng dẫn thiết lập kiểm thử
Được tổ chức theo độ phức tạp của tệp:
- Đơn giản (5 phút) - 5 tệp
- Dễ (15-30 phút) - 12 tệp
- Trung bình (30-60 phút) - 10 tệp
- Phức tạp (1-2 giờ) - 4 tệp
- Hạ tầng quan trọng - 3 tệp
Phù hợp nhất cho: Nhóm triển khai, lập trình viên, viết code thực tế
🎯 Cách Sử Dụng Tài Liệu Này
Tình huống 1: Tôi là Quản Lý Dự Án
- Đọc EXPLORATION_SUMMARY.txt (15 phút)
- Chia sẻ timeline và công sức với nhóm
- Tham khảo IMPLEMENTATION_QUICK_REFERENCE.md để biết định nghĩa từng giai đoạn
Tình huống 2: Tôi là Tech Lead Lập Kế Hoạch Công Việc
- Đọc EXPLORATION_SUMMARY.txt (15 phút)
- Đọc IMPLEMENTATION_QUICK_REFERENCE.md (30 phút)
- Lướt qua FILE_MAPPING_GUIDE.md để hiểu phân bố độ phức tạp
- Tạo task sprint dựa trên đánh giá độ phức tạp của từng tệp
Tình huống 3: Tôi là Lập Trình Viên Triển Khai i18n
- Xem nhanh EXPLORATION_SUMMARY.txt (5 phút)
- Đọc sâu các phần liên quan đến task của bạn trong docs/audits/FRONTEND_EXPLORATION.md
- Dùng FILE_MAPPING_GUIDE.md như hướng dẫn từng bước
- Tham khảo các ví dụ code và pseudo-code được cung cấp
Tình huống 4: Tôi Đang Triển Khai Sửa Lỗi A11y
- Đọc phần A11y trong EXPLORATION_SUMMARY.txt
- Tham khảo phần A11y trong IMPLEMENTATION_QUICK_REFERENCE.md
- Dùng Giai đoạn 5 của FILE_MAPPING_GUIDE.md để biết các sửa lỗi cụ thể
- Kiểm tra danh sách xác nhận trước khi coi là hoàn thành
🗂️ Tổ Chức Tài Liệu Theo Chủ Đề
Về Triển Khai i18n
- EXPLORATION_SUMMARY.txt → phần "Text Content Requiring Translation"
- IMPLEMENTATION_QUICK_REFERENCE.md → Strategic Entry Points, Giai đoạn 1-2
- FILE_MAPPING_GUIDE.md → Giai đoạn 1-3, phần cấu trúc tệp message
Về Sửa Lỗi Accessibility
- EXPLORATION_SUMMARY.txt → phần "Accessibility Audit Findings"
- IMPLEMENTATION_QUICK_REFERENCE.md → phần A11y Implementation Priority
- FILE_MAPPING_GUIDE.md → Giai đoạn 5, cập nhật component cụ thể
Về Thiết Lập Hạ Tầng
- IMPLEMENTATION_QUICK_REFERENCE.md → Danh sách kiểm tra Giai đoạn 1
- FILE_MAPPING_GUIDE.md → Giai đoạn 1: Infrastructure Setup
Về Kiểm Thử & QA
- IMPLEMENTATION_QUICK_REFERENCE.md → phần Testing Strategy
- FILE_MAPPING_GUIDE.md → Giai đoạn 6: Test Setup Updates, Validation Checklist
📊 Thống Kê Chính
| Chỉ số | Giá trị |
|---|---|
| Tệp trong apps/web | 90+ |
| Tệp cần cập nhật | 50-60 |
| Mục văn bản cần dịch | 200+ |
| Component cần cập nhật | 35+ |
| Trang cần cập nhật | 15+ |
| Lỗi A11y phát hiện | 10+ |
| Thời gian triển khai ước tính | 19-27 giờ (~3-4 ngày) |
| Thiết lập i18n hiện tại | Không có (0%) |
| Độ phủ A11y hiện tại | 60-70% |
✅ Danh Sách Kiểm Tra Trước Triển Khai
Trước khi bắt đầu triển khai:
- Xem lại EXPLORATION_SUMMARY.txt
- Cài đặt gói next-intl (
npm install next-intl) - Phân bổ 3-4 ngày cho triển khai đầy đủ
- Nhóm có kinh nghiệm với Next.js App Router
- Có quyền truy cập axe DevTools để kiểm thử accessibility
- Lập kế hoạch kiểm thử với screen reader (NVDA hoặc JAWS)
🚀 Khởi Đầu Nhanh
Buổi Sáng Ngày 1
- Đọc EXPLORATION_SUMMARY.txt (15 phút)
- Đọc IMPLEMENTATION_QUICK_REFERENCE.md (30 phút)
- Cài đặt next-intl:
npm install next-intl - Tạo tệp cấu hình i18n:
i18n/config.ts - Tạo tệp message:
public/locales/en.jsonvàvi.json
Buổi Chiều Ngày 1
- Bắt đầu với Giai đoạn 1 của FILE_MAPPING_GUIDE.md
- Cập nhật middleware.ts (30-45 phút)
- Cập nhật app/layout.tsx (30 phút)
Ngày 2
- Tiếp tục với Giai đoạn 2-3 của FILE_MAPPING_GUIDE.md
- Cập nhật các tệp core layout và page
- Trích xuất văn bản từ validation
Ngày 3
- Tiếp tục Giai đoạn 3-4
- Cập nhật các component còn lại
- Bắt đầu sửa lỗi A11y
Ngày 4
- Hoàn thành sửa lỗi A11y
- Chạy kiểm thử toàn diện
- Sửa các vấn đề phát hiện được
📞 Câu Hỏi Trong Khi Triển Khai?
Tham khảo các phần cụ thể:
H: Cách cấu trúc tệp message như thế nào?
Đ: Xem FILE_MAPPING_GUIDE.md → Giai đoạn 1 → cấu trúc public/locales/en.json
H: Tôi cập nhật tệp nào trước? Đ: Xem IMPLEMENTATION_QUICK_REFERENCE.md → Critical Files for i18n
H: Cách thêm focus trapping vào dialog như thế nào?
Đ: Xem FILE_MAPPING_GUIDE.md → Giai đoạn 5 → components/ui/dialog.tsx
H: Timeline cho công việc này là bao lâu? Đ: Xem EXPLORATION_SUMMARY.txt → phần Implementation Timeline
H: Có những thắng lợi nhanh nào tôi có thể làm ngay không? Đ: Có! Xem IMPLEMENTATION_QUICK_REFERENCE.md → Quick Win Opportunities
🔍 Chỉ Số Chất Lượng Tài Liệu
| Chỉ số | Giá trị |
|---|---|
| Độ sâu phân tích | Rất kỹ lưỡng |
| Độ phủ tệp | 100% của app/web |
| Ví dụ code được cung cấp | Có (40+ đoạn) |
| Pseudo-code được bao gồm | Có |
| Đánh giá độ phức tạp | Có (chi tiết) |
| Độ phủ kiểm thử | Có |
| Danh sách xác nhận | Có |
📌 Lưu Ý Quan Trọng
-
Không có i18n hiện tại: Tất cả đều được hardcode bằng tiếng Việt. Đây là triển khai i18n từ đầu (greenfield).
-
A11y đã được thực hiện một phần: Nền tảng tốt đã có sẵn (HTML ngữ nghĩa, ARIA label, skip link), nhưng quản lý focus và một số thuộc tính ARIA vẫn còn thiếu.
-
Công nghệ đã sẵn sàng: Tất cả thư viện cần thiết đã được cài đặt. Đây là dự án tái cấu trúc/bổ sung, không phải thay đổi framework.
-
TypeScript hỗ trợ: Type safety sẽ phát hiện nhiều vấn đề trong quá trình tái cấu trúc.
-
Kiểm thử rất quan trọng: Cả hai locale đều cần được kiểm thử kỹ lưỡng.
📚 Tài Nguyên Bổ Sung
Tài liệu tham chiếu:
- Next.js App Router: cấu trúc thư mục
/app - Thư viện next-intl: cấu hình và thiết lập
- WCAG 2.1 AA: tiêu chuẩn accessibility
- Tailwind CSS: phương pháp tạo kiểu
- Zod: schema validation
- TypeScript: type safety
🎓 Lộ Trình Học Tập
Nếu bạn mới làm quen với codebase này:
- Bắt đầu với EXPLORATION_SUMMARY.txt để có cái nhìn tổng quan
- Đọc phần "Directory Structure Overview" trong docs/audits/FRONTEND_EXPLORATION.md
- Hiểu cấu trúc App Router
- Xem lại các pattern component hiện tại
- Sau đó bắt đầu triển khai với FILE_MAPPING_GUIDE.md
📝 Phiên Bản & Lịch Sử
Phiên bản hiện tại: 1.0 - Trước khi triển khai
Được tạo: 9 tháng 4, 2026
Loại phân tích: Rất kỹ lưỡng
Mức độ tin cậy: CAO ✅
Trạng thái: Sẵn sàng triển khai
🎯 Tiêu Chí Thành Công
Triển khai hoàn thành khi:
- ✅ Cả hai route
/en/*và/vi/*đều hoạt động - ✅ Tất cả văn bản hardcoded đến từ tệp message
- ✅ Metadata thay đổi theo locale
- ✅ Thông báo validation được dịch
- ✅ Tất cả enum sử dụng i18n
- ✅ Focus trap hoạt động trong dialog
- ✅ Lỗi form được liên kết với aria-describedby
- ✅ Tất cả nút icon có aria-label
- ✅ Độ tương phản màu đạt WCAG AA
- ✅ Điều hướng bằng bàn phím hoạt động
- ✅ Kiểm thử vượt qua cho cả hai locale
- ✅ Kiểm tra axe DevTools vượt qua
Sẵn sàng triển khai? Bắt đầu với EXPLORATION_SUMMARY.txt, sau đó chuyển sang FILE_MAPPING_GUIDE.md 🚀