Your IP : 216.73.216.79
# Panduan Sistem Multi-Bahasa (Translation)
## Ringkasan
Sistem multi-bahasa mempunyai **2 lapisan**:
| Lapisan | Fungsi | Storage |
|---------|--------|---------|
| **App Translation (UI Strings)** | Label nav, button, footer, text statik | Table `app_translations` + helper `t()` |
| **Content Translation** | Data content (artikel, slider, video, dll) | Table translation berasingan / self-referencing |
---
## 1. App Translation — UI Strings
### Cara Guna
Dalam mana-mana Blade template (termasuk component dalam DB):
```blade
{{ t('login') }} <!-- Output: Log Masuk / Login / 登录 -->
{{ t('register') }} <!-- Output: Daftar / Register / 注册 -->
{{ t('nonexistent') }} <!-- Output: nonexistent (fallback ke key) -->
{{ t('key', 'Default') }} <!-- Output: 'Default' kalau key tak wujud -->
```
### Admin Panel
`/admin/app-translation` → CRUD untuk semua keys.
| key | ms | en | zh |
|-----|----|----|-----|
| login | Log Masuk | Login | 登录 |
| register | Daftar | Register | 注册 |
| dynaweb4_desc | DYNAWEB4 adalah... | DYNAWEB4 is... | DYNAWEB4 是一个... |
| Utama | Utama | Home | 首页 |
| Hubungi Kami | Hubungi Kami | Contact Us | 联系我们 |
- **Index**:
- **Default view**: Accordion group by language (collapse/expand), paginate language groups 5/page
- **Filtered view** (`?lang=ms`): Flat list filtered by language, paginate 10/page
- "Showing" displays language count (not key count)
- Dropdown: "All Languages" (no dashes)
- **Create**: Tambah key + value untuk 1 bahasa
- **Edit**: Edit semua bahasa untuk 1 key sekali gus
### Helper `t()` Function
**File:** `app/Helpers/Translation.php`
```php
function t(string $key, ?string $default = null): string
{
static $data = [];
$locale = session('locale', 'ms');
if (!isset($data[$locale])) {
$data[$locale] = AppTranslation::where('lang', $locale)
->pluck('value', 'key')->all();
}
return $data[$locale][$key] ?? $default ?? $key;
}
```
- Auto-detect locale dari session (default `'ms'`)
- Cache guna `static` variable dalam 1 request
- Fallback: key → default → key asal
---
## 2. Content Translation
Sistem guna **dua pattern** untuk content translation:
| Pattern | Modules | Cara Kerja |
|---------|---------|------------|
| **Separate Table** | ContentArticle, ContentSlider, ContentVideo, ContentCalendar, ContentPhotoGallery, ContentApplication | Data translatable dalam table berasingan, di-link via `*_parent_id` |
| **Self-Referencing (Sibling)** | ContentDownload, ContentImage, ContentPhotoList | Translation adalah row lain dalam table yang sama, `*_main = 1` untuk parent |
### Language Switching Flow
```
User klik "ENGLISH"
↓
GET /lang/en
↓
Route set session('locale', 'en')
↓
PortalHandler inject $lang = session('locale', 'ms')
↓
Components query content WHERE *_language = $lang
```
### Language Switching Route
**File:** `routes/web.php`
```php
Route::get('/lang/{code}', function ($code) {
$valid = DB::table('ref')->where('cat', 'LANGUAGE')
->where('code', $code)->exists();
if ($valid) session(['locale' => $code]);
return redirect()->back();
})->name('lang.switch');
```
Navbar links:
```blade
<a href="{{ url('lang/ms') }}">MALAY</a>
<a href="{{ url('lang/en') }}">ENGLISH</a>
<a href="{{ url('lang/zh') }}">中文</a>
```
### PortalHandler — Inject $lang
**File:** `app/Services/PortalHandler.php`
```php
$lang = session('locale', 'ms');
$vars = [
'lang' => $lang,
// ... variables lain
];
```
Semua component, page content, dan layout dapat akses `$lang`.
---
## 3. Pattern: Separate Translation Table
Digunakan oleh: **ContentArticle**, **ContentSlider**, **ContentVideo**, **ContentCalendar**, **ContentPhotoGallery**, **ContentApplication**
### Table Structure
```
content_article content_article_translation
┌──────────────────┐ ┌─────────────────────────────────┐
│ article_id (PK) │◄──┐ │ article_translation_id (PK) │
│ article_code │ └───│ article_translation_parent_id │
│ article_status │ │ article_translation_title │
│ ... │ │ article_translation_content │
└──────────────────┘ │ article_translation_language │
│ article_translation_main │
└─────────────────────────────────┘
```
### Query Pattern
```php
// PortalHandler components guna $lang dari session
$news = ContentArticle::with(['translations' => function($q) use ($lang) {
$q->where('article_translation_language', $lang);
}])->where('article_category', 'NEWS')->get();
```
### Modules
| Module | Parent Table | Translation Table | FK | Language Field |
|--------|-------------|-------------------|----|---------------|
| ContentArticle | `content_article` | `content_article_translation` | `article_translation_parent_id` | `article_translation_language` |
| ContentSlider | `content_slider` | `content_slider_translation` | `slider_translation_parent_id` | `slider_translation_language` |
| ContentVideo | `content_video` | `content_video_translation` | `video_translation_parent_id` | `video_translation_language` |
| ContentCalendar | `content_calendar` | `content_calendar_translation` | `calendar_translation_parent_id` | `calendar_translation_language` |
| ContentPhotoGallery | `content_photo_gallery` | `content_photo_gallery_translations` | `gallery_translation_parent_id` | `gallery_translation_language` |
| ContentApplication | `content_applications` | `content_application_translations` | `application_translation_parent_id` | `application_translation_language` |
---
## 4. Pattern: Self-Referencing (Sibling)
Digunakan oleh: **ContentDownload**, **ContentImage**, **ContentPhotoList**
### Table Structure
```
content_downloads
┌──────────────────────────────┐
│ download_id (PK) │
│ download_main = 1/0 │ ← 1 = parent, 0 = sibling
│ download_parent_id (FK) │ ← null utk parent, pointing ke parent utk sibling
│ download_language = 'ms' │
│ download_title │
│ download_file │
│ ... │
└──────────────────────────────┘
```
### Query Pattern
```php
// Parent row dalam locale semasa
$downloads = ContentDownload::where('download_language', $lang)
->where('download_status', 'ACTIVE')
->orderBy('download_category')->get();
```
### Modules
| Module | Table | Main Flag | Parent FK | Language Field |
|--------|-------|-----------|-----------|---------------|
| ContentDownload | `content_downloads` | `download_main` | `download_parent_id` | `download_language` |
| ContentImage | `content_images` | `image_main` | `image_parent_id` | `image_language` |
| ContentPhotoList | `content_photo_list` | `photo_main` | `photo_parent_id` | `photo_language` |
---
## 5. Frontend Menu Translation
Menu names disimpan dalam table `frontend_menu` dalam BM. PortalHandler akan auto-translate menggunakan `t()`.
**File:** `app/Services/PortalHandler.php`
```php
$translateMenuName = function ($name) {
return t($name); // lookup dalam app_translations
};
// Build menu tree
$menuTree = $buildTree($publicMappings);
// Translate all menu names
array_walk_recursive($menuTree, function (&$v, $k) use ($translateMenuName) {
if ($k === 'menu_name') $v = $translateMenuName($v);
});
```
Keys yang perlu ada dalam `app_translations`:
- `Utama`, `Mengenai Kami`, `Sejarah`, `Visi Misi`, `Carta Organisasi`, `Piagam Pelanggan`
- `Perkhidmatan`, `Dalam Talian`, `e-Permohonan`, `FAQ`, `Muat Turun`
- `Media`, `Berita`, `Galeri Foto`, `Video`, `Penerbitan`, `Hubungi Kami`
---
## 6. Seeder
### ContentTranslationSeeder
**File:** `database/seeders/portal/ContentTranslationSeeder.php`
Seed data awal untuk `app_translations` table. Guard: `count() > 0`.
```php
$data = [
['key' => 'login', 'ms' => 'Log Masuk', 'en' => 'Login', 'zh' => '登录'],
['key' => 'Utama', 'ms' => 'Utama', 'en' => 'Home', 'zh' => '首页'],
// ... lebih banyak keys
];
```
### Content Seeders
Semua portal content seeders (ContentSliderSeeder, ContentVideoSeeder, dll) sekarang insert **ms, en, zh** untuk setiap content. Guard guna `->where('column', 'CATEGORY')->count()` spesifik mengikut kategori.
---
## 7. Admin Module: App Translation
**Routes:** `/admin/app-translation`
| Item | Nama |
|------|------|
| Table | `app_translations` |
| Model | `AppTranslation` |
| Controller | `AppTranslationController` |
| View folder | `appTranslation/` |
| Menu | Translations (dalam group Content) |
| Permission | `app-translation.view`, `.create`, `.update`, `.delete` |
### Features
- **Index**: Accordion group by language (collapse/expand), paginate by language 5/page, flat filter by language 10/page, search, dropdown "All Languages"
- **Create**: Add key + value for 1 language
- **Edit**: Edit all languages for a key simultaneously
- **Delete**: Delete entire key (all languages)
---
## 8. Language Codes (ISO 639-1)
| Code | Language (Ref) |
|------|---------------|
| `ms` | Bahasa Melayu |
| `en` | English |
| `zh` | 中文 (Mandarin) |
Defined in `ref` table with `cat = 'LANGUAGE'`. Admin boleh tambah bahasa baru di menu Ref.
---
## 9. Files Reference
| File | Function |
|------|----------|
| `app/Helpers/Translation.php` | Helper `t()` function |
| `app/Models/Backend/AppTranslation.php` | Model untuk `app_translations` |
| `app/Http/Controllers/Backend/AppTranslationController.php` | CRUD controller + paginate by language |
| `app/Http/Requests/Backend/AppTranslationRequest.php` | Validation |
| `app/Services/PortalHandler.php` | Inject `$lang`, translate menu names |
| `resources/views/backend/module/appTranslation/*.blade.php` | Admin views |
| `resources/views/vendor/pagination/custom.blade.php` | Pagination template (showing language count) |
| `database/seeders/portal/ContentTranslationSeeder.php` | Seeder app_translations |
| `database/migrations/2026_07_05_000001_create_app_translations_table.php` | Migration |
| `routes/web.php` | Route `/lang/{code}` + admin routes |
| `database/seeders/portal/ContentSliderSeeder.php` | Slider seeder (ms, en, zh) |
| `database/seeders/portal/ContentVideoSeeder.php` | Video seeder (ms, en, zh) |
| `database/seeders/portal/ContentCalendarSeeder.php` | Calendar seeder (ms, en, zh) |
| `database/seeders/portal/ContentGallerySeeder.php` | Gallery seeder (ms, en, zh) |
| `database/seeders/portal/ContentApplicationSeeder.php` | Application seeder (ms, en, zh) |
| `database/seeders/portal/ContentDownloadSeeder.php` | Download seeder (ms, en, zh) |
| `database/seeders/portal/ContentImageSeeder.php` | Image seeder (ms, en, zh) |
| `database/seeders/portal/ContentArticleAboutUsSeeder.php` | Article PRESS (ms, en, zh) |
| `database/seeders/portal/ContentArticleFaqSeeder.php` | Article FAQ (ms, en, zh) |
| `database/seeders/portal/ContentNewsSeeder.php` | Article NEWS (ms, en, zh) |
| `database/seeders/portal/WebSiteBackupSeeder.php` | Portal components with `$lang` queries |