# IAI FLOW HTML I18N USAGE GUIDE
# HƯỚNG DẪN CHUẨN HTML CHO I18N VÀ AUTO TRANSLATE

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 HTML usage standard for internationalization in IAI Flow.

Tài liệu này định nghĩa chuẩn chính thức cho cách sử dụng HTML phục vụ quốc tế hóa trong IAI Flow.

The goal is to ensure:

Mục tiêu là đảm bảo:

• every developer uses the same markup rules  
• UI language remains consistent across the platform  
• Vietnamese stays the primary user-facing language  
• English remains the official global support language  
• auto translation is applied only in controlled ways  

• mọi developer dùng cùng một quy tắc markup  
• ngôn ngữ giao diện thống nhất trên toàn bộ nền tảng  
• tiếng Việt luôn là ngôn ngữ ưu tiên ở phía người dùng  
• tiếng Anh là ngôn ngữ hỗ trợ toàn cầu chính thức  
• dịch tự động chỉ được dùng trong phạm vi có kiểm soát  

This document is mandatory for:

Tài liệu này là bắt buộc đối với:

• frontend developers  
• template builders  
• UI designers  
• AI code generation  
• contributors working on HTML pages  

• lập trình viên frontend  
• người dựng template  
• người thiết kế UI  
• AI sinh code  
• người đóng góp làm việc với các trang HTML  

---

# 2. Official Language Model
# 2. Mô hình ngôn ngữ chính thức

IAI Flow uses the following language model:

IAI Flow dùng mô hình ngôn ngữ sau:

• source language: Vietnamese  
• official global language: English  
• additional languages: automatic translation or future language packs  

• ngôn ngữ nguồn: tiếng Việt  
• ngôn ngữ toàn cầu chính thức: tiếng Anh  
• các ngôn ngữ bổ sung: dịch tự động hoặc language pack trong tương lai  

This means:

Điều này có nghĩa là:

1. Vietnamese is the primary authoring language for user-facing UI.  
2. English is the secondary official language.  
3. Other languages must not be hardcoded directly in templates unless officially supported.  

1. Tiếng Việt là ngôn ngữ soạn UI chính cho người dùng.  
2. Tiếng Anh là ngôn ngữ chính thức thứ hai.  
3. Các ngôn ngữ khác không được hardcode trực tiếp trong template nếu chưa được hỗ trợ chính thức.  

---

# 3. Core Rule
# 3. Quy tắc cốt lõi

All user-facing HTML text must follow one of these approved methods:

Toàn bộ text giao diện hiển thị cho người dùng trong HTML phải đi theo một trong các cách được phép sau:

### Method A — `data-i18n`
For official UI strings with dictionary keys.

Dùng cho text giao diện chính thức có key trong dictionary.

### Method B — `data-auto-translate`
For controlled runtime translation of text that is not yet part of the official dictionary.

Dùng cho dịch tự động runtime đối với text chưa nằm trong dictionary chính thức.

### Method C — `data-auto-translate-attr`
For translating HTML attributes such as placeholder, title, aria-label.

Dùng để dịch các thuộc tính HTML như placeholder, title, aria-label.

Hardcoded visible UI text without one of these methods is not allowed, except for temporary prototypes explicitly marked for replacement.

Không được hardcode text giao diện hiển thị nếu không dùng một trong ba cách trên, trừ prototype tạm thời có ghi chú rõ sẽ thay thế.

---

# 4. Required File Structure
# 4. Cấu trúc file bắt buộc

The i18n system depends on the following files:

Hệ i18n phụ thuộc vào các file sau:

```text
assets/
 ├ i18n.js
 ├ auto-translate-engine.js
 ├ ui-language-switcher.js
 └ i18n/
     ├ vi.json
     └ en.json

Correct example

Ví dụ đúng:

<button data-i18n="runWorkflow"></button>
``` id="0vyrqj"

The engine will replace the content using `vi.json` or `en.json`.

Engine sẽ thay nội dung theo `vi.json` hoặc `en.json`.

## Another example
## Ví dụ khác

```html
<h1 data-i18n="dashboard"></h1>
<p data-i18n="appDescription"></p>
``` id="4u9abn"

## Rule
## Quy tắc

When a string exists in `vi.json` and `en.json`, `data-i18n` must always be used.

Khi một chuỗi đã tồn tại trong `vi.json` và `en.json`, luôn phải dùng `data-i18n`.

Do not hardcode Vietnamese or English directly in the element body if a dictionary key already exists.

Không hardcode tiếng Việt hoặc tiếng Anh trực tiếp vào phần thân element nếu key dictionary đã tồn tại.

---

# 6. Method B — Auto Translate Text Content
# 6. Cách B — Dịch tự động cho nội dung text

Use `data-auto-translate` only when:

Chỉ dùng `data-auto-translate` khi:

• the text is not yet part of the official dictionary  
• the page contains content that may vary dynamically  
• the string is secondary and not part of the product’s canonical UI copy  

• text chưa nằm trong dictionary chính thức  
• trang có nội dung thay đổi linh hoạt  
• chuỗi là phần phụ, không phải canonical UI copy của sản phẩm  

## Correct example
## Ví dụ đúng

```html
<div data-auto-translate>
This experimental panel shows orchestration diagnostics.
</div>
``` id="xl4p7w"

## Important rule
## Quy tắc quan trọng

If a text becomes stable and repeated across pages, it must be promoted into `vi.json` and `en.json`, and `data-i18n` must replace `data-auto-translate`.

Nếu một text trở thành ổn định và lặp đi lặp lại trên nhiều trang, nó phải được đưa vào `vi.json` và `en.json`, sau đó dùng `data-i18n` thay cho `data-auto-translate`.

Auto translate is not a replacement for proper localization.

Dịch tự động không thay thế cho bản địa hóa chính thức.

---

# 7. Method C — Auto Translate HTML Attributes
# 7. Cách C — Dịch thuộc tính HTML

Use `data-auto-translate-attr` when the user-facing text is inside attributes.

Dùng `data-auto-translate-attr` khi text hiển thị cho người dùng nằm trong thuộc tính.

Common attributes:

Các thuộc tính thường dùng:

• placeholder  
• title  
• aria-label  
• alt  

## Correct example
## Ví dụ đúng

```html
<input
  placeholder="Tìm node..."
  data-auto-translate-attr="placeholder"
/>
``` id="4b93v8"

```html
<button
  title="Chạy workflow"
  data-auto-translate-attr="title"
>
  ▶
</button>
``` id="ym6kfo"

```html
<img
  src="assets/diagram.png"
  alt="Sơ đồ workflow AI"
  data-auto-translate-attr="alt"
/>
``` id="eo62v6"

## Multiple attributes
## Nhiều thuộc tính cùng lúc

```html
<input
  placeholder="Nhập prompt..."
  title="Prompt cho workflow"
  data-auto-translate-attr="placeholder,title"
/>
``` id="jsk6mb"

---

# 8. Recommended Hybrid Pattern
# 8. Mẫu kết hợp được khuyến nghị

The recommended pattern is:

Mẫu được khuyến nghị là:

• canonical UI text → `data-i18n`  
• temporary dynamic text → `data-auto-translate`  
• placeholder/title/alt → `data-auto-translate-attr`  
• Vietnamese remains the authoring base for UX  
• English remains the official global dictionary  

• text giao diện chuẩn → `data-i18n`  
• text động tạm thời → `data-auto-translate`  
• placeholder/title/alt → `data-auto-translate-attr`  
• tiếng Việt là nền soạn UX  
• tiếng Anh là dictionary toàn cầu chính thức  

---

# 9. Canonical UI Rule
# 9. Quy tắc UI chính thức

The following elements must always use `data-i18n`:

Các thành phần sau luôn phải dùng `data-i18n`:

• navigation  
• buttons  
• menus  
• sidebar labels  
• dashboard section titles  
• workflow builder actions  
• node library labels  
• agent manager labels  
• settings labels  
• status labels  
• notifications  
• empty states  
• validation messages  
• core product copy  

• điều hướng  
• nút bấm  
• menu  
• nhãn sidebar  
• tiêu đề section trong dashboard  
• hành động của workflow builder  
• nhãn thư viện node  
• nhãn trình quản lý agent  
• nhãn phần cài đặt  
• nhãn trạng thái  
• thông báo  
• empty state  
• validation message  
• nội dung cốt lõi của sản phẩm  

These are official product strings and must not depend only on auto translate.

Đây là các chuỗi sản phẩm chính thức và không được chỉ phụ thuộc vào auto translate.

---

# 10. Fallback Rules
# 10. Quy tắc fallback

The language system follows this order:

Hệ ngôn ngữ đi theo thứ tự sau:

1. user selected language  
2. official dictionary for that language  
3. fallback dictionary `en.json`  
4. base Vietnamese or English source text  
5. auto translate if configured  
6. raw key if nothing else is available  

1. ngôn ngữ người dùng đã chọn  
2. dictionary chính thức cho ngôn ngữ đó  
3. fallback dictionary `en.json`  
4. text nguồn tiếng Việt hoặc tiếng Anh  
5. auto translate nếu được cấu hình  
6. hiện key thô nếu không còn gì khác  

This ensures the UI never fully breaks.

Điều này đảm bảo UI không bao giờ gãy hoàn toàn.

---

# 11. Required HTML Examples
# 11. Các ví dụ HTML bắt buộc

## Example 1 — Button
## Ví dụ 1 — Nút bấm

```html
<button class="btn" data-i18n="runWorkflow"></button>
``` id="wt8b2e"

## Example 2 — Page title
## Ví dụ 2 — Tiêu đề trang

```html
<h1 data-i18n="workflowBuilder"></h1>
``` id="y80afq"

## Example 3 — Search input
## Ví dụ 3 — Ô tìm kiếm

```html
<input
  type="text"
  placeholder="Tìm node..."
  data-auto-translate-attr="placeholder"
/>
``` id="btg5wu"

## Example 4 — Card content
## Ví dụ 4 — Nội dung card

```html
<div class="card">
  <h3 data-i18n="nodeLibrary"></h3>
  <p data-i18n="appDescription"></p>
</div>
``` id="ig7qdn"

## Example 5 — Runtime translated content
## Ví dụ 5 — Nội dung dịch runtime

```html
<div class="info-box" data-auto-translate>
This panel displays runtime diagnostics for orchestration tasks.
</div>
``` id="it7s65"

---

# 12. HTML Authoring Rules
# 12. Quy tắc soạn HTML

When writing HTML templates:

Khi viết template HTML:

### Rule 1
Do not hardcode button labels.

Không hardcode nhãn nút bấm.

### Rule 2
Do not hardcode navigation labels.

Không hardcode nhãn điều hướng.

### Rule 3
Do not mix Vietnamese and English manually in the same visible UI string unless the design explicitly requires bilingual display.

Không tự trộn tiếng Việt và tiếng Anh trong cùng một chuỗi UI hiển thị trừ khi thiết kế chủ động yêu cầu song ngữ.

### Rule 4
Do not use automatic translation for canonical navigation or product core actions.

Không dùng auto translate cho điều hướng chính thức hoặc hành động cốt lõi của sản phẩm.

### Rule 5
Do not invent unofficial language keys.

Không tự tạo key ngôn ngữ không theo chuẩn đã thống nhất.

### Rule 6
If new repeated UI text appears, add it to both `vi.json` and `en.json`.

Nếu có text UI mới lặp lại nhiều lần, phải thêm vào cả `vi.json` và `en.json`.

---

# 13. Bilingual Display Rule
# 13. Quy tắc hiển thị song ngữ

Bilingual display is allowed when strategically useful.

Hiển thị song ngữ được phép khi có giá trị chiến lược.

Recommended use cases:

Các trường hợp nên dùng:

• onboarding for mixed audiences  
• investor pages  
• public project pages  
• educational documentation  
• landing pages for global visibility  

• onboarding cho nhóm người dùng pha trộn  
• trang investor  
• trang giới thiệu dự án công khai  
• tài liệu hướng dẫn  
• landing page hướng tới nhận diện toàn cầu  

Example:

Ví dụ:

```html
<h2>
  <span>Trình xây workflow</span>
  <small>Workflow Builder</small>
</h2>
``` id="hhctc4"

However, application control surfaces such as dashboards should usually display a single active interface language.

Tuy nhiên, các màn hình điều khiển như dashboard thường chỉ nên hiển thị một ngôn ngữ giao diện đang được kích hoạt.

---

# 14. Accessibility Rule
# 14. Quy tắc accessibility

Translation must also apply to accessibility attributes.

Dịch phải áp dụng cả cho thuộc tính accessibility.

Required attributes include:

Các thuộc tính bắt buộc chú ý:

• aria-label  
• title  
• alt  
• placeholder  

Example:

Ví dụ:

```html
<button
  aria-label="Chạy workflow"
  title="Chạy workflow"
  data-auto-translate-attr="aria-label,title"
>
  ▶
</button>
``` id="z2i8vm"

Ignoring accessibility text creates language inconsistency.

Bỏ qua text accessibility sẽ gây lệch chuẩn ngôn ngữ.

---

# 15. Developer Checklist
# 15. Checklist cho developer

Before merging any HTML page, verify:

Trước khi merge bất kỳ trang HTML nào, hãy kiểm tra:

• all repeated UI labels use `data-i18n`  
• dynamic non-canonical copy uses `data-auto-translate` only where appropriate  
• placeholders and titles use `data-auto-translate-attr`  
• no core button text is hardcoded  
• no unsupported language is manually injected  
• Vietnamese-first UX remains intact  

• tất cả nhãn UI lặp lại đã dùng `data-i18n`  
• text động không phải canonical chỉ dùng `data-auto-translate` khi phù hợp  
• placeholder và title dùng `data-auto-translate-attr`  
• không hardcode text nút bấm cốt lõi  
• không chèn thủ công ngôn ngữ không được hỗ trợ  
• trải nghiệm ưu tiên tiếng Việt vẫn được giữ  

---

# 16. AI Code Generation Rule
# 16. Quy tắc với AI sinh code

When AI generates HTML for IAI Flow, it must follow these rules:

Khi AI sinh HTML cho IAI Flow, phải tuân theo:

• canonical labels → `data-i18n`  
• temporary content → `data-auto-translate` if needed  
• input attributes → `data-auto-translate-attr`  
• no uncontrolled hardcoded English-only UI  
• no uncontrolled hardcoded Vietnamese-only UI for reusable product templates  

• nhãn chuẩn → `data-i18n`  
• nội dung tạm thời → `data-auto-translate` nếu cần  
• thuộc tính input → `data-auto-translate-attr`  
• không hardcode UI chỉ tiếng Anh một cách không kiểm soát  
• không hardcode UI chỉ tiếng Việt một cách không kiểm soát trong template tái sử dụng  

AI-generated HTML that violates these rules must be corrected before merge.

HTML sinh bởi AI nếu vi phạm các quy tắc này phải được sửa trước khi merge.

---

# 17. Forbidden Patterns
# 17. Các mẫu bị cấm

The following patterns are not allowed:

Các mẫu sau không được phép:

## Forbidden 1
```html
<button>Run workflow</button>
``` id="rx6z9d"

Reason: hardcoded canonical button label.

Lý do: hardcode nút bấm cốt lõi.

## Forbidden 2
```html
<a>Dashboard</a>
``` id="0isn3a"

Reason: hardcoded navigation label.

Lý do: hardcode điều hướng.

## Forbidden 3
```html
<input placeholder="Search node..." />
``` id="x6p6df"

Reason: placeholder is user-facing and should be translatable.

Lý do: placeholder hiển thị cho người dùng và phải dịch được.

## Forbidden 4
```html
<div data-auto-translate data-i18n="dashboard"></div>
``` id="1h1j77"

Reason: do not mix canonical and automatic translation on the same UI string.

Lý do: không trộn canonical translation và auto translation trên cùng một chuỗi UI.

---

# 18. Official Final Principle
# 18. Nguyên tắc chính thức cuối cùng

The official final principle is:

Nguyên tắc chính thức cuối cùng là:

**In HTML, every user-facing string must be intentionally classified as either official dictionary text or controlled auto-translated text. Nothing visible should be linguistically accidental.**

**Trong HTML, mọi chuỗi hiển thị cho người dùng phải được phân loại có chủ đích: hoặc là text chính thức từ dictionary, hoặc là text dịch tự động có kiểm soát. Không có gì hiển thị được phép là ngẫu nhiên về mặt ngôn ngữ.**

This is the rule that locks language consistency for the entire platform.

Đây là quy tắc khóa tính nhất quán ngôn ngữ cho toàn bộ nền tảng.

---

# End of Document
# Kết thúc tài liệu