# IAI FLOW LANGUAGE STANDARD # TIÊU CHUẨN NGÔN NGỮ IAI FLOW Version: 1.0 Project: IAI Flow Ecosystem: iai.one Owner: Trần Hà Tâm --- # 1. Purpose # 1. Mục đích This document defines the official language standard for the IAI Flow project and the broader iai.one ecosystem. Tài liệu này định nghĩa tiêu chuẩn ngôn ngữ chính thức cho dự án IAI Flow và hệ sinh thái iai.one. The purpose of this standard is to ensure: Mục đích của tiêu chuẩn này là đảm bảo: • language consistency across the platform • a Vietnamese-first user experience • strong international compatibility • clean engineering standards for developers • clear separation between programming language and user interface language • tính thống nhất ngôn ngữ trên toàn bộ nền tảng • trải nghiệm ưu tiên tiếng Việt • khả năng tương thích quốc tế mạnh • tiêu chuẩn kỹ thuật rõ ràng cho developer • sự tách bạch giữa ngôn ngữ lập trình và ngôn ngữ giao diện This standard applies to: Tiêu chuẩn này áp dụng cho: • developers • AI code generation • UI design • documentation • APIs • database design • workflow systems • node libraries • automation agents • lập trình viên • hệ thống AI sinh code • thiết kế giao diện • tài liệu • API • thiết kế cơ sở dữ liệu • hệ thống workflow • thư viện node • tác nhân tự động hóa All contributors must follow this document. Tất cả người tham gia dự án phải tuân thủ tài liệu này. --- # 2. Foundational Position # 2. Lập trường nền tảng iai.one belongs to a company or organization based in the United States. iai.one thuộc về một công ty hoặc tổ chức đặt tại Hoa Kỳ. However, the founder is Vietnamese, the project originates from Vietnamese leadership, and the platform intentionally prioritizes Vietnamese as its primary user-facing language. Tuy nhiên, người sáng lập là người Việt Nam, dự án được khởi tạo từ tư duy lãnh đạo Việt Nam, và nền tảng chủ động ưu tiên tiếng Việt là ngôn ngữ chính ở phía người dùng. Therefore, IAI Flow must be treated as: Vì vậy, IAI Flow phải được hiểu là: • a global platform • built with international engineering standards • legally and organizationally compatible with the United States and international markets • but culturally and linguistically Vietnamese-first in the user experience • một nền tảng toàn cầu • được xây dựng theo chuẩn kỹ thuật quốc tế • tương thích pháp lý và tổ chức với Hoa Kỳ và thị trường quốc tế • nhưng ưu tiên trải nghiệm ngôn ngữ và bản sắc Việt Nam ở phía người dùng This is not a contradiction. Đây không phải là mâu thuẫn. It is the official identity of the platform. Đây là bản sắc chính thức của nền tảng. --- # 3. Core Language Principle # 3. Nguyên tắc ngôn ngữ cốt lõi The official language model of the platform is: Mô hình ngôn ngữ chính thức của nền tảng là: Programming language = English User interface language = Vietnamese first International interface language = English Documentation language = Vietnamese primary, English secondary when needed Ngôn ngữ lập trình = Tiếng Anh Ngôn ngữ giao diện = Ưu tiên tiếng Việt Ngôn ngữ giao diện quốc tế = Tiếng Anh Ngôn ngữ tài liệu = Tiếng Việt là chính, tiếng Anh là phụ khi cần This rule must be preserved across all layers of the system. Quy tắc này phải được giữ xuyên suốt trên tất cả các lớp của hệ thống. --- # 4. Language Layers # 4. Các lớp ngôn ngữ The project uses three primary language layers. Dự án sử dụng ba lớp ngôn ngữ chính. --- ## Layer 1 — Programming Language ## Lớp 1 — Ngôn ngữ lập trình Used in: Áp dụng cho: • source code • file names • folder names • variables • functions • classes • interfaces • database schema • migration files • API routes • JSON keys • workflow engine internals • node identifiers • agent identifiers • mã nguồn • tên file • tên thư mục • biến • hàm • class • interface • schema cơ sở dữ liệu • file migration • route API • key JSON • phần lõi workflow engine • định danh node • định danh agent Language rule: Quy tắc ngôn ngữ: **English only** **Chỉ dùng tiếng Anh** Examples: Ví dụ: ```text createWorkflow() runWorkflow() nodeRegistry workflowEngine executionState agentCoordinator Dưới đây là file hoàn chỉnh mới cho: docs/language-standard.md Bản này đã chỉnh lại đúng tinh thần anh nói: • iai.one là hệ thống của công ty / tổ chức tại Hoa Kỳ • nhưng ưu tiên ngôn ngữ tiếng Việt • vì người sáng lập là người Việt Nam • dự án mang định hướng toàn cầu, nhưng gốc văn hóa và trải nghiệm ưu tiên là Việt Nam • code vẫn dùng tiếng Anh • UI mặc định ưu tiên tiếng Việt • tiếng Anh là ngôn ngữ quốc tế phụ trợ ⸻ # IAI FLOW LANGUAGE STANDARD # TIÊU CHUẨN NGÔN NGỮ IAI FLOW Version: 1.0 Project: IAI Flow Ecosystem: iai.one Owner: Trần Hà Tâm --- # 1. Purpose # 1. Mục đích This document defines the official language standard for the IAI Flow project and the broader iai.one ecosystem. Tài liệu này định nghĩa tiêu chuẩn ngôn ngữ chính thức cho dự án IAI Flow và hệ sinh thái iai.one. The purpose of this standard is to ensure: Mục đích của tiêu chuẩn này là đảm bảo: • language consistency across the platform • a Vietnamese-first user experience • strong international compatibility • clean engineering standards for developers • clear separation between programming language and user interface language • tính thống nhất ngôn ngữ trên toàn bộ nền tảng • trải nghiệm ưu tiên tiếng Việt • khả năng tương thích quốc tế mạnh • tiêu chuẩn kỹ thuật rõ ràng cho developer • sự tách bạch giữa ngôn ngữ lập trình và ngôn ngữ giao diện This standard applies to: Tiêu chuẩn này áp dụng cho: • developers • AI code generation • UI design • documentation • APIs • database design • workflow systems • node libraries • automation agents • lập trình viên • hệ thống AI sinh code • thiết kế giao diện • tài liệu • API • thiết kế cơ sở dữ liệu • hệ thống workflow • thư viện node • tác nhân tự động hóa All contributors must follow this document. Tất cả người tham gia dự án phải tuân thủ tài liệu này. --- # 2. Foundational Position # 2. Lập trường nền tảng iai.one belongs to a company or organization based in the United States. iai.one thuộc về một công ty hoặc tổ chức đặt tại Hoa Kỳ. However, the founder is Vietnamese, the project originates from Vietnamese leadership, and the platform intentionally prioritizes Vietnamese as its primary user-facing language. Tuy nhiên, người sáng lập là người Việt Nam, dự án được khởi tạo từ tư duy lãnh đạo Việt Nam, và nền tảng chủ động ưu tiên tiếng Việt là ngôn ngữ chính ở phía người dùng. Therefore, IAI Flow must be treated as: Vì vậy, IAI Flow phải được hiểu là: • a global platform • built with international engineering standards • legally and organizationally compatible with the United States and international markets • but culturally and linguistically Vietnamese-first in the user experience • một nền tảng toàn cầu • được xây dựng theo chuẩn kỹ thuật quốc tế • tương thích pháp lý và tổ chức với Hoa Kỳ và thị trường quốc tế • nhưng ưu tiên trải nghiệm ngôn ngữ và bản sắc Việt Nam ở phía người dùng This is not a contradiction. Đây không phải là mâu thuẫn. It is the official identity of the platform. Đây là bản sắc chính thức của nền tảng. --- # 3. Core Language Principle # 3. Nguyên tắc ngôn ngữ cốt lõi The official language model of the platform is: Mô hình ngôn ngữ chính thức của nền tảng là: Programming language = English User interface language = Vietnamese first International interface language = English Documentation language = Vietnamese primary, English secondary when needed Ngôn ngữ lập trình = Tiếng Anh Ngôn ngữ giao diện = Ưu tiên tiếng Việt Ngôn ngữ giao diện quốc tế = Tiếng Anh Ngôn ngữ tài liệu = Tiếng Việt là chính, tiếng Anh là phụ khi cần This rule must be preserved across all layers of the system. Quy tắc này phải được giữ xuyên suốt trên tất cả các lớp của hệ thống. --- # 4. Language Layers # 4. Các lớp ngôn ngữ The project uses three primary language layers. Dự án sử dụng ba lớp ngôn ngữ chính. --- ## Layer 1 — Programming Language ## Lớp 1 — Ngôn ngữ lập trình Used in: Áp dụng cho: • source code • file names • folder names • variables • functions • classes • interfaces • database schema • migration files • API routes • JSON keys • workflow engine internals • node identifiers • agent identifiers • mã nguồn • tên file • tên thư mục • biến • hàm • class • interface • schema cơ sở dữ liệu • file migration • route API • key JSON • phần lõi workflow engine • định danh node • định danh agent Language rule: Quy tắc ngôn ngữ: **English only** **Chỉ dùng tiếng Anh** Examples: Ví dụ: ```text createWorkflow() runWorkflow() nodeRegistry workflowEngine executionState agentCoordinator Incorrect examples: Ví dụ sai: taoWorkflow() chayWorkflow() thuVienNode boDieuPhoiAgent Vietnamese must never be used in programming identifiers. Tiếng Việt không được dùng trong tên biến, tên hàm, tên class hoặc định danh kỹ thuật. ⸻ Layer 2 — User Interface Language Lớp 2 — Ngôn ngữ giao diện người dùng Used in: Áp dụng cho: • buttons • menus • labels • titles • navigation • dashboards • forms • empty states • alerts • error messages • tooltips • help text • onboarding screens • product copy • nút bấm • menu • nhãn • tiêu đề • điều hướng • bảng điều khiển • biểu mẫu • trạng thái rỗng • cảnh báo • thông báo lỗi • tooltip • phần trợ giúp • màn hình hướng dẫn • nội dung sản phẩm Language priority: Thứ tự ưu tiên ngôn ngữ: 1. Vietnamese 2. English 3. Tiếng Việt 4. Tiếng Anh Default behavior: Hành vi mặc định: • users in Vietnam should see Vietnamese first • users outside Vietnam may see English by default if no Vietnamese preference is explicitly chosen • Vietnamese must always remain available as a first-class language option • người dùng tại Việt Nam phải thấy tiếng Việt trước • người dùng ngoài Việt Nam có thể thấy tiếng Anh mặc định nếu chưa có lựa chọn tiếng Việt rõ ràng • tiếng Việt luôn phải tồn tại như một lựa chọn hạng nhất của hệ thống Example: Ví dụ: Chạy workflow Run workflow ⸻ Layer 3 — Documentation Language Lớp 3 — Ngôn ngữ tài liệu Used in: Áp dụng cho: • project docs • developer docs • setup guides • architecture docs • internal standards • product guides • public introduction materials • tài liệu dự án • tài liệu developer • hướng dẫn cài đặt • tài liệu kiến trúc • tiêu chuẩn nội bộ • hướng dẫn sản phẩm • tài liệu giới thiệu công khai Documentation principle: Nguyên tắc tài liệu: Vietnamese is primary. English is secondary when necessary for technical or global collaboration. Tiếng Việt là chính. Tiếng Anh là phụ khi cần cho kỹ thuật hoặc hợp tác quốc tế. This means documentation may be: Điều này có nghĩa tài liệu có thể là: • Vietnamese only • bilingual Vietnamese and English • English only in highly technical internal specifications if necessary • chỉ tiếng Việt • song ngữ Việt và Anh • chỉ tiếng Anh trong các đặc tả kỹ thuật nội bộ chuyên sâu nếu thật sự cần However, for founder-facing and Vietnam-facing project documentation, Vietnamese remains the preferred default. Tuy nhiên, đối với tài liệu phục vụ người sáng lập và định hướng người dùng Việt Nam, tiếng Việt vẫn là mặc định ưu tiên. ⸻ 5. Official Identity Statement 5. Tuyên bố bản sắc chính thức The official identity statement of the platform is: Tuyên bố bản sắc chính thức của nền tảng là: IAI Flow is a global platform built from Vietnamese leadership, Vietnamese priority, and international engineering standards. IAI Flow là nền tảng toàn cầu được xây dựng từ tư duy lãnh đạo Việt Nam, ưu tiên tiếng Việt và vận hành theo chuẩn kỹ thuật quốc tế. This statement replaces any weaker wording that does not clearly affirm Vietnamese priority. Câu này thay thế cho mọi cách diễn đạt yếu hơn, không làm rõ được tính ưu tiên tiếng Việt. The platform is not merely “originating from Vietnam.” Nền tảng không chỉ là “xuất phát từ Việt Nam.” The platform is intentionally designed to keep Vietnamese as a foundational user language while remaining globally operable. Nền tảng được chủ động thiết kế để giữ tiếng Việt là ngôn ngữ nền tảng ở phía người dùng, đồng thời vẫn vận hành được ở quy mô toàn cầu. ⸻ 6. Language Detection Rules 6. Quy tắc phát hiện ngôn ngữ IAI Flow must automatically determine the interface language using this priority order: IAI Flow phải tự động xác định ngôn ngữ giao diện theo thứ tự ưu tiên sau: 1. user saved preference 2. explicit URL or route language override 3. country or region detection 4. browser language 5. system default 6. lựa chọn đã lưu của người dùng 7. ghi đè ngôn ngữ từ URL hoặc route 8. nhận diện quốc gia hoặc khu vực 9. ngôn ngữ trình duyệt 10. mặc định hệ thống Default rules: Quy tắc mặc định: • Vietnam users → Vietnamese • international users → English unless they explicitly choose Vietnamese • manual language switch always overrides auto detection • người dùng tại Việt Nam → tiếng Việt • người dùng quốc tế → tiếng Anh trừ khi họ chủ động chọn tiếng Việt • lựa chọn ngôn ngữ thủ công luôn ghi đè tự động phát hiện The language engine must be implemented in: Hệ i18n phải được triển khai tại: assets/i18n.js Supported core languages: Ngôn ngữ lõi được hỗ trợ: vi en Future supported languages may include: Trong tương lai có thể hỗ trợ thêm: zh jp kr es fr de ⸻ 7. Internationalization Architecture 7. Kiến trúc i18n All UI text must be stored in language dictionaries. Tất cả text giao diện phải được lưu trong dictionary ngôn ngữ. Required structure: Cấu trúc bắt buộc: assets/ ├ i18n.js └ i18n/ ├ vi.json └ en.json HTML elements must use data-i18n. Phần tử HTML phải dùng data-i18n. Example: Ví dụ: The language engine replaces the text at runtime. Hệ i18n sẽ thay thế nội dung tại thời điểm chạy. Hardcoded UI strings should be avoided whenever practical. Không nên hardcode chuỗi giao diện nếu có thể dùng dictionary. ⸻ 8. Vietnamese-First Interface Rule 8. Quy tắc giao diện ưu tiên tiếng Việt For all product pages intended for general users, the default authoring mindset must be Vietnamese-first. Đối với tất cả các trang sản phẩm hướng tới người dùng phổ thông, tư duy viết giao diện mặc định phải là ưu tiên tiếng Việt. This means: Điều này có nghĩa là: • Vietnamese should be written first in product planning • UI labels should be reviewed in Vietnamese before English • product flow should feel natural to Vietnamese users • English translation should support global users, not replace Vietnamese identity • tiếng Việt phải được viết trước trong quá trình thiết kế sản phẩm • nhãn giao diện phải được duyệt bằng tiếng Việt trước rồi mới tới tiếng Anh • luồng sử dụng phải tự nhiên với người Việt • bản tiếng Anh phục vụ mở rộng quốc tế, không thay thế bản sắc Việt của nền tảng ⸻ 9. Naming Rules 9. Quy tắc đặt tên All programming identifiers must use English. Tất cả định danh lập trình phải dùng tiếng Anh. Files Tên file workflow-engine.js node-registry.js node-connection-engine.js workflow-state-manager.js Variables Biến workflowId nodeType executionState agentConfig currentLanguage Classes and modules Class và module WorkflowEngine NodeRegistry AgentRunner ExecutionController LanguageManager API routes Route API /api/workflows /api/nodes /api/agents /api/executions Vietnamese must never be used in technical identifiers. Không dùng tiếng Việt trong định danh kỹ thuật. ⸻ 10. Node Naming Rules 10. Quy tắc tên node Internal node identifiers must use English. Định danh nội bộ của node phải dùng tiếng Anh. Examples: Ví dụ: AI Node API Node Logic Node Database Node Vector Node Webhook Node Delay Node However, UI display may be localized. Tuy nhiên, phần hiển thị giao diện có thể bản địa hóa. Vietnamese UI examples: Ví dụ hiển thị tiếng Việt: Node AI Node API Node Logic Node Cơ sở dữ liệu Node Webhook Node Trì hoãn The internal system must always preserve English identifiers. Hệ thống nội bộ luôn phải giữ định danh tiếng Anh. ⸻ 11. UI Writing Style 11. Phong cách viết UI User interface language must be: Ngôn ngữ giao diện phải: • short • clear • direct • action-oriented • easy to understand • ngắn • rõ • trực tiếp • thiên về hành động • dễ hiểu Correct Vietnamese examples: Ví dụ tiếng Việt đúng: Chạy workflow Lưu workflow Xóa node Thêm node Mở dashboard Incorrect examples: Ví dụ tiếng Việt không nên dùng: Tiến hành khởi chạy workflow Thực hiện việc thêm một node mới The UI should be simple and confident. Giao diện phải đơn giản và dứt khoát. ⸻ 12. Error Messages 12. Thông báo lỗi Error messages shown to users should support localization. Thông báo lỗi hiển thị cho người dùng phải hỗ trợ bản địa hóa. Preferred user-facing style: Kiểu hiển thị ưu tiên cho người dùng: Vietnamese primary English secondary if needed Tiếng Việt là chính Tiếng Anh là phụ nếu cần Example: Ví dụ: Không thể chạy workflow Unable to run workflow Internal logs remain English only. Nhật ký nội bộ vẫn chỉ dùng tiếng Anh. ⸻ 13. Commit Messages 13. Commit Git All Git commit messages must use English. Tất cả commit Git phải dùng tiếng Anh. Examples: Ví dụ: fix workflow execution bug add node connection validation update workflow runner improve language detection logic Vietnamese must not be used in commit messages. Không dùng tiếng Việt trong commit. ⸻ 14. Code Comments 14. Comment trong code All source code comments must use English. Tất cả comment trong code phải dùng tiếng Anh. Example: Ví dụ: // validate node connection before execution Avoid Vietnamese comments in source files. Không dùng comment tiếng Việt trong file code. ⸻ 15. AI Generated Code Rules 15. Quy tắc code sinh bởi AI When AI tools generate code for IAI Flow, they must follow these rules: Khi AI sinh code cho IAI Flow, phải tuân thủ các quy tắc sau: Programming language → English Variables and functions → English File names → English UI text → dictionary based No hardcoded UI language unless explicitly temporary Ngôn ngữ lập trình → tiếng Anh Biến và hàm → tiếng Anh Tên file → tiếng Anh Text giao diện → đi qua dictionary Không hardcode ngôn ngữ giao diện trừ khi tạm thời và có chủ đích AI-generated code that violates this standard must be corrected before merge. Code sinh bởi AI nếu vi phạm tiêu chuẩn này phải được sửa trước khi merge. ⸻ 16. Documentation Rules 16. Quy tắc tài liệu Documentation in the iai.one ecosystem should follow: Tài liệu trong hệ sinh thái iai.one nên theo: • Vietnamese first for founder-facing and Vietnam-facing materials • bilingual when useful • English for strictly technical portability when necessary • tiếng Việt trước đối với tài liệu phục vụ người sáng lập và người dùng Việt • song ngữ khi hữu ích • tiếng Anh cho tính di động kỹ thuật khi thật sự cần This means not every document must be bilingual, but the system must preserve Vietnamese priority where it matters. Điều này có nghĩa là không phải tài liệu nào cũng bắt buộc song ngữ, nhưng hệ thống phải giữ ưu tiên tiếng Việt ở những nơi quan trọng. ⸻ 17. Expansion Strategy 17. Chiến lược mở rộng The language system must support future international expansion. Hệ ngôn ngữ phải hỗ trợ mở rộng quốc tế trong tương lai. Possible language pack structure: Cấu trúc gói ngôn ngữ có thể mở rộng: assets/i18n/ vi.json en.json zh.json jp.json kr.json es.json fr.json However, Vietnamese remains a permanent core language and must never become a second-class option. Tuy nhiên, tiếng Việt luôn là ngôn ngữ lõi cố định và không bao giờ được trở thành lựa chọn hạng hai. ⸻ 18. Official Final Principle 18. Nguyên tắc chính thức cuối cùng The official final principle of IAI Flow is: Nguyên tắc chính thức cuối cùng của IAI Flow là: IAI Flow is a global platform operated with international standards, built by a Vietnamese founder, and intentionally designed to prioritize Vietnamese in the user experience. IAI Flow là nền tảng toàn cầu vận hành theo chuẩn quốc tế, được xây dựng bởi người sáng lập Việt Nam, và được chủ động thiết kế để ưu tiên tiếng Việt trong trải nghiệm người dùng. Therefore: Vì vậy: Programming language = English User interface = Vietnamese first Global interface = English supported Documentation = Vietnamese priority with English support where needed Ngôn ngữ lập trình = tiếng Anh Giao diện người dùng = ưu tiên tiếng Việt Giao diện quốc tế = có hỗ trợ tiếng Anh Tài liệu = ưu tiên tiếng Việt, có hỗ trợ tiếng Anh khi cần This principle is mandatory across the entire ecosystem. Nguyên tắc này là bắt buộc trên toàn bộ hệ sinh thái. ⸻ End of Document Kết thúc tài liệu