docs: Introduce dedicated Vietnamese documentation and update READMEs to link to localized content for marketing services.

2026-01-18 23:05:58 +07:00
parent 5c39c4aa93
commit f6c485c9b0
14 changed files with 4766 additions and 86 deletions
--- a/.agent/skills/documentation/SKILL.md
+++ b/.agent/skills/documentation/SKILL.md
@@ -67,9 +67,78 @@ services/my-service-net/
 **Key Rules:**
 - `docs/en/` and `docs/vi/` MUST mirror each other (same files, same structure)
 - Each language folder is MONOLINGUAL (no bilingual mixing)
+- **Filenames**: EN uses English (UPPERCASE), VI uses Vietnamese (kebab-case)
 - Service root `README.md` links to both EN/VI documentation
 - Mermaid diagrams MUST use dark color palette (see [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md))
- `ARCHITECTURE.md` is MANDATORY, `README.md` is MANDATORY, other files optional
+- `ARCHITECTURE.md`/`kien-truc.md` is MANDATORY, `README.md`/`gioi-thieu.md` is MANDATORY, other files optional
+
+### Vietnamese Filename Conventions / Quy Ước Đặt Tên Tiếng Việt
+
+**Standard EN/VI Filename Mapping:**
+
+| English (docs/en/) | Vietnamese (docs/vi/) | Description |
+|-------------------|----------------------|-------------|
+| `README.md` | `gioi-thieu.md` | Service introduction, quick start |
+| `ARCHITECTURE.md` | `kien-truc.md` | Architecture documentation |
+| `API.md` | `api.md` | API reference (technical term) |
+| `DEPLOYMENT.md` | `trien-khai.md` | Deployment guide |
+| `CONFIGURATION.md` | `cau-hinh.md` | Configuration guide |
+| `TESTING.md` | `kiem-thu.md` | Testing guide |
+| `TROUBLESHOOTING.md` | `khac-phuc-su-co.md` | Troubleshooting |
+| `MIGRATION.md` | `di-chuyen-du-lieu.md` | Migration guide |
+| `PERFORMANCE.md` | `hieu-nang.md` | Performance optimization |
+| `SECURITY.md` | `bao-mat.md` | Security guidelines |
+
+**Service-Specific Examples:**
+
+| Service Type | EN Filename | VI Filename |
+|-------------|------------|-------------|
+| WhatsApp | `WHATSAPP_SETUP.md` | `cai-dat-whatsapp.md` |
+| WhatsApp | `AI_CHATBOT_GUIDE.md` | `huong-dan-chatbot-ai.md` |
+| WhatsApp | `AUTOMATION_GUIDE.md` | `huong-dan-tu-dong-hoa.md` |
+| Facebook | `FACEBOOK_SETUP.md` | `cai-dat-facebook.md` |
+| Twitter/X | `TWITTER_SETUP.md` | `cai-dat-twitter.md` |
+| Zalo | `ZALO_SETUP.md` | `cai-dat-zalo.md` |
+
+**Naming Rules for Vietnamese Files:**
+
+1. **Kebab-case**: All lowercase, words separated by hyphens (`-`)
+   - ✅ `kien-truc.md`, `huong-dan-chatbot-ai.md`
+   - ❌ `KIEN-TRUC.md`, `Kien_Truc.md`, `KienTruc.md`
+
+2. **Vietnamese without diacritics**: Use non-accented Vietnamese
+   - ✅ `kien-truc` (not `kiến-trúc`)
+   - ✅ `cau-hinh` (not `cấu-hình`)
+   - ✅ `trien-khai` (not `triển-khai`)
+
+3. **Descriptive and clear**: Use full words, avoid abbreviations
+   - ✅ `huong-dan-chatbot-ai.md` (clear)
+   - ❌ `hd-chatbot.md` (abbreviated)
+
+4. **Technical terms**: Keep English for technical/API terms
+   - ✅ `api.md` (lowercase)
+   - ✅ `webhook.md`
+   - ✅ `oauth.md`
+
+**Directory Structure Example:**
+
+```
+services/mkt-whatsapp-service-net/docs/
+├── en/
+│   ├── README.md
+│   ├── ARCHITECTURE.md
+│   ├── API.md
+│   ├── WHATSAPP_SETUP.md
+│   ├── AI_CHATBOT_GUIDE.md
+│   └── AUTOMATION_GUIDE.md
+└── vi/
+    ├── gioi-thieu.md
+    ├── kien-truc.md
+    ├── api.md
+    ├── cai-dat-whatsapp.md
+    ├── huong-dan-chatbot-ai.md
+    └── huong-dan-tu-dong-hoa.md
+```


 ## Key Patterns / Mẫu Chính
@@ -104,32 +173,100 @@ Nội dung bằng tiếng Việt...

 ### Service README Template

+**For service root `README.md` (bilingual with links to language-specific docs):**
+
 ```markdown
-# Service Name / Tên Dịch Vụ
+# Service Name

-> **EN**: Brief description in English
-> **VI**: Mô tả ngắn gọn bằng tiếng Việt
+> **EN**: [English Documentation](docs/en/README.md)  
+> **VI**: [Tài liệu Tiếng Việt](docs/vi/gioi-thieu.md)

-## Features / Tính Năng
- Feature 1 / Tính năng 1
+## Quick Links

-## Prerequisites / Yêu Cầu
- Node.js 20+
- PostgreSQL (Neon)
+- 📖 [Architecture](docs/en/ARCHITECTURE.md) / [Kiến trúc](docs/vi/kien-truc.md)
+- 🚀 [API Reference](docs/en/API.md) / [Tài liệu API](docs/vi/api.md)
+- ⚙️ [Configuration](docs/en/README.md#configuration) / [Cấu hình](docs/vi/gioi-thieu.md#cấu-hình)
+
+## Tech Stack
+
+- .NET 8 / Node.js 20
+- PostgreSQL
+- Redis
+- RabbitMQ
+
+## Development

-## Quick Start / Bắt Đầu Nhanh
 ```bash
+dotnet build && dotnet run
+# or
 pnpm install && pnpm dev
 ```

-## Configuration / Cấu Hình
+See detailed documentation:
+- **English**: [docs/en/](docs/en/)
+- **Tiếng Việt**: [docs/vi/](docs/vi/)
+```

-| Variable | Description / Mô Tả | Default |
-|----------|---------------------|---------|
-| PORT | Server port / Cổng server | 5000 |
+**For `docs/en/README.md` (English only, detailed):**
+
+```markdown
+# Service Name
+
+Brief description in English.
+
+## Features
+- Feature 1
+- Feature 2
+
+## Prerequisites
+- .NET 8 / Node.js 20+
+- PostgreSQL 15+
+
+## Quick Start
+```bash
+dotnet run
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 5000 |
+| DATABASE_URL | PostgreSQL connection | - |

 ## API Endpoints
-See [API Documentation](../../docs/api/openapi/service-name.yaml)
+See [API Documentation](API.md)
+```
+
+**For `docs/vi/gioi-thieu.md` (Vietnamese only, mirrors EN content):**
+
+```markdown
+# Tên Dịch Vụ
+
+Mô tả ngắn gọn bằng tiếng Việt.
+
+## Tính Năng
+- Tính năng 1
+- Tính năng 2
+
+## Yêu Cầu
+- .NET 8 / Node.js 20+
+- PostgreSQL 15+
+
+## Bắt Đầu Nhanh
+```bash
+dotnet run
+```
+
+## Cấu Hình
+
+| Biến | Mô Tả | Mặc Định |
+|------|-------|---------|
+| PORT | Cổng server | 5000 |
+| DATABASE_URL | Kết nối PostgreSQL | - |
+
+## API Endpoints
+Xem [Tài liệu API](api.md)
 ```

 ### Guide Template