Dưới đây là hai file hoàn chỉnh để khóa chuẩn i18n cho toàn bộ team dev của dự án IAI Flow / iai.one. Sau khi hai file này có trong repo, hệ ngôn ngữ của dự án sẽ được khóa chuẩn ở mức production platform. ⸻ 1️⃣ docs/i18n-developer-checklist.md # IAI FLOW I18N DEVELOPER CHECKLIST # CHECKLIST KIỂM TRA NGÔN NGỮ CHO DEV Project: IAI Flow Platform: iai.one Version: 1.0 Maintainer: Trần Hà Tâm --- # 1. Purpose # 1. Mục đích This checklist ensures that every developer working on IAI Flow follows the same language rules. Checklist này đảm bảo mọi developer làm việc trên IAI Flow tuân thủ cùng một chuẩn ngôn ngữ. The checklist must be used before: Checklist này phải được kiểm tra trước khi: • committing frontend code • merging pull requests • releasing UI updates • generating UI via AI • commit code frontend • merge pull request • release cập nhật giao diện • sinh code UI bằng AI --- # 2. Official Language Model # 2. Mô hình ngôn ngữ IAI Flow follows a **Vietnamese-first global model**. IAI Flow sử dụng mô hình **Vietnamese-first global**. Priority order: Thứ tự ưu tiên: 1️⃣ Vietnamese (source language) 2️⃣ English (global language) 3️⃣ auto translation for other languages 1️⃣ Tiếng Việt (ngôn ngữ nguồn) 2️⃣ Tiếng Anh (ngôn ngữ toàn cầu) 3️⃣ dịch tự động cho các ngôn ngữ khác --- # 3. Mandatory UI Rules # 3. Quy tắc UI bắt buộc Before committing any HTML, confirm the following. Trước khi commit HTML, xác nhận các điều sau. --- ### Navigation All navigation labels must use `data-i18n`. Tất cả nhãn điều hướng phải dùng `data-i18n`. Example: ```html ⸻ Buttons All buttons must use data-i18n. Tất cả nút bấm phải dùng data-i18n. Example: ⸻ Form inputs Form attributes must support translation. Thuộc tính form phải hỗ trợ dịch. Example: ⸻ Section titles Section titles must use data-i18n. Tiêu đề section phải dùng data-i18n. Example:

⸻ 4. Forbidden Patterns 4. Mẫu bị cấm These patterns are not allowed. Các mẫu sau không được phép. ⸻ Hardcoded UI text Reason: Canonical UI text must not be hardcoded. ⸻ Hardcoded navigation Dashboard Reason: Navigation must be translatable. ⸻ Hardcoded placeholder Reason: Placeholder must support translation. ⸻ 5. Correct Translation Patterns 5. Mẫu dịch đúng ⸻ Official UI string Use dictionary. Dùng dictionary. ⸻ Temporary dynamic text Use auto translate. Dùng auto translate.
This diagnostic panel shows runtime workflow status.
⸻ Attribute translation Use attribute translation. Dùng dịch thuộc tính. ⸻ 6. Dictionary Rules 6. Quy tắc dictionary Every key in vi.json must exist in en.json. Mỗi key trong vi.json phải tồn tại trong en.json. Example: { "runWorkflow": "Chạy workflow" } { "runWorkflow": "Run workflow" } Missing keys are not allowed. Không được thiếu key. ⸻ 7. Required Dev Tools 7. Công cụ kiểm tra Developers must run: Dev phải chạy: node scripts/check-i18n.js before pushing code. trước khi push code. ⸻ 8. Review Checklist 8. Checklist review Before merging PR confirm: Trước khi merge PR kiểm tra: ☑ Navigation uses data-i18n ☑ Buttons use data-i18n ☑ Inputs use data-auto-translate-attr ☑ No hardcoded UI labels ☑ vi.json and en.json are synchronized ☑ check-i18n script passes ⸻ 9. AI Generated Code Rule 9. Quy tắc với code sinh bởi AI AI-generated HTML must follow the same rules. HTML sinh bởi AI phải tuân thủ cùng quy tắc. Required: Bắt buộc: • canonical UI → data-i18n • attributes → data-auto-translate-attr • dynamic copy → data-auto-translate ⸻ 10. Final Principle 10. Nguyên tắc cuối cùng Every visible string must be intentionally classified. Mọi chuỗi hiển thị phải được phân loại rõ ràng. Either: Hoặc: • dictionary translation • controlled auto translation No uncontrolled language. Không có ngôn ngữ ngẫu nhiên. ⸻ End of Document --- # 2️⃣ docs/i18n-key-naming-standard.md ```markdown # IAI FLOW I18N KEY NAMING STANDARD # CHUẨN ĐẶT TÊN KEY NGÔN NGỮ Project: IAI Flow Platform: iai.one --- # 1. Purpose # 1. Mục đích This document defines how translation keys must be named. Tài liệu này định nghĩa cách đặt tên key dịch. Consistent key naming is required to: Chuẩn đặt tên key giúp: • maintain translation consistency • simplify developer workflow • allow automation tools to work • giữ tính nhất quán ngôn ngữ • đơn giản hóa workflow dev • hỗ trợ automation --- # 2. General Rules # 2. Quy tắc chung Translation keys must follow: Key dịch phải tuân theo: camelCase naming. Ví dụ: runWorkflow nodeLibrary saveWorkflow agentManager Do not use: Không dùng: snake_case UPPERCASE spaces --- # 3. Prefix Categories # 3. Phân loại key Keys should be grouped by feature. Key nên được nhóm theo tính năng. --- ### Navigation navDashboard navWorkflow navNodes navAgents navSettings --- ### Buttons btnSave btnCancel btnRunWorkflow btnAddNode btnDelete --- ### Status statusRunning statusStopped statusCompleted statusFailed --- ### Forms formName formDescription formPrompt formTimeout --- ### Errors errorConnectionFailed errorInvalidInput errorNodeTimeout --- ### Messages msgWorkflowSaved msgNodeCreated msgExecutionStarted --- # 4. Section Titles # 4. Tiêu đề section Use descriptive keys. Dùng key rõ nghĩa. Example: workflowBuilder nodeLibrary agentManager systemLogs executionHistory --- # 5. Placeholder Keys # 5. Key placeholder Use `placeholder` prefix. Ví dụ: placeholderSearchNode placeholderEnterPrompt placeholderWorkflowName --- # 6. Tooltip Keys # 6. Key tooltip Use `tooltip` prefix. Ví dụ: tooltipRunWorkflow tooltipAddNode tooltipDeleteNode --- # 7. Accessibility Keys # 7. Key accessibility Use `aria` prefix. Ví dụ: ariaRunWorkflow ariaSearchNode ariaOpenMenu --- # 8. Length Rules # 8. Quy tắc độ dài Keys must be: Key phải: • short • descriptive • readable --- Bad: btn x1 workflowActionButton Good: btnRunWorkflow btnAddNode btnSaveWorkflow --- # 9. Canonical UI Keys # 9. Key UI chuẩn Core UI keys must not change. Key UI cốt lõi không được đổi. Examples: dashboard workflowBuilder nodeLibrary agentManager settings Changing these breaks UI consistency. Đổi các key này sẽ phá UI. --- # 10. JSON Structure # 10. Cấu trúc JSON Example `vi.json` { “runWorkflow”: “Chạy workflow”, “saveWorkflow”: “Lưu workflow”, “nodeLibrary”: “Thư viện node” } Example `en.json` { “runWorkflow”: “Run workflow”, “saveWorkflow”: “Save workflow”, “nodeLibrary”: “Node library” } --- # 11. Key Evolution # 11. Phát triển key If new UI features appear: Nếu UI mới xuất hiện: 1️⃣ add key to `vi.json` 2️⃣ add same key to `en.json` 3️⃣ run `check-i18n.js` --- # 12. Forbidden Key Patterns # 12. Key bị cấm Not allowed: Không được dùng: text1 text2 tempString --- # 13. Final Principle # 13. Nguyên tắc cuối cùng Keys represent meaning, not UI position. Key đại diện cho ý nghĩa, không phải vị trí UI. Good key: btnRunWorkflow Bad key: topRightButton --- End of Document