StayWise PMS：基於 Laravel 12 與 Filament 3 的結構化多語系架構

本文深入說明 StayWise PMS 的多語系設計與實作細節，涵蓋 靜態 UI 翻譯、動態資料翻譯、Filament 與 Livewire 的整合、權限與審計的語系閉環，並提供最佳實務與範例程式碼，讓開發者能在真實專案中直接套用。
👉 原始碼可參考：GitHub 專案

---

一、前言：多維度的國際化策略

在 SaaS 環境中，國際化不只是字串切換，而是把「語言」視為系統的一等公民。StayWise 採用 雙層策略：

• 靜態 UI 翻譯：介面文字、導覽、按鈕、欄位標籤等放在 resources/lang/{locale}/，以模組化檔案管理（如 nav.php、dashboard.php），前端可直接呼叫 __('nav.booking_mgmt.check_in')。
• 動態資料翻譯：使用 spatie/laravel-translatable，將可翻譯的商業資料（房型名稱、菜單品項、房間描述）存成 JSON 欄位，模型自動回傳當前語系的值。

這樣的分層讓 UI 與資料各司其職：UI 保持一致性，資料則提供多語版本。

---

二、靜態語系檔的層級化管理

設計原則

• 模組化：每個功能模組一個子陣列（booking_mgmt、dashboard、fb_mgmt）。
• 一致性 Key 命名：module.section.key 或 module.key。
• 描述性 Key：避免 label1，改用 check_in、urgent_fix 等可讀性高的 key。

範例：resources/lang/zh_TW/nav.php

return [
    'booking_mgmt' => [
        'title' => '訂房管理',
        'check_in' => '入住日期',
        'check_out' => '退房日期',
        'sources' => [
            'online' => '線上訂房',
            'walk_in' => '現場訂房',
            'ota' => 'OTA 平台',
        ],
    ],
    'dashboard' => [
        'title' => '儀表板',
        'urgent_fix' => '需立即處理',
        'calendar_desc' => '顯示房況與預訂狀態',
    ],
    'system_mgmt' => [
        'title' => '系統管理',
        'roles' => [
            'admin' => '系統管理員',
            'manager' => '經理',
            'receptionist' => '櫃檯',
        ],
    ],
];

前端呼叫範例

{{ __('nav.booking_mgmt.title') }}
{{ __('nav.booking_mgmt.sources.' . $booking->source) }}

---

三、Livewire 與 Filament 的整合

• 驗證與欄位名稱一致性：在 Livewire 元件中綁定翻譯，確保錯誤訊息與 UI 一致。
• Filament Resource 與翻譯欄位：結合 Spatie Translatable，表單欄位可直接支援多語。

範例：Livewire 驗證

protected function validationAttributes()
{
    return [
        'checkInDate' => __('nav.booking_mgmt.check_in'),
        'guestName'   => __('nav.guest_crm.name'),
    ];
}

範例：Filament Resource

TextInput::make('name')
    ->label(__('fb_mgmt.item_name'))
    ->reactive()
    ->required();

---

四、動態資料翻譯與資料庫設計

• 模型設定

class RoomType extends Model
{
    use HasTranslations;
    public $translatable = ['name', 'description'];
}

• 資料庫欄位

ALTER TABLE room_types ADD COLUMN name JSON NULL;

• Seeder 範例

RoomType::create([
    'name' => ['zh_TW' => '雙人房', 'en' => 'Double Room'],
    'description' => ['zh_TW' => '含早餐', 'en' => 'Includes breakfast'],
]);

---

五、權限與審計的語系閉環

• 權限名稱本地化：角色與權限顯示名稱放在 nav.php，確保管理介面在地化。
• Activity Log 可讀化：事件記錄轉換為語系字串，讓營運人員更易理解。

---

六、最佳實務與性能考量

1. 快取：翻譯字串快取到 Redis；熱門資料短期快取。
2. Fallback：設定 fallback_locale，避免缺字串。
3. 測試：單元測試、整合測試、E2E 測試。
4. CI 與部署：翻譯檔一致性檢查、快取清理。

---

七、補充工具與自動化

• 缺失翻譯 Key 偵測：在 AppServiceProvider 中加入 missing callback。
• 翻譯同步管理：使用 kenepa/translation-manager 或自建 Filament Resource。
• CSV 匯入/匯出：方便大量上傳多語內容。

---

八、目錄建議

resources/lang/
  en/nav.php
  zh_TW/nav.php
app/Models/RoomType.php
app/Http/Livewire/BookingForm.php
app/Providers/AppServiceProvider.php
database/seeders/TranslationSeeder.php

---

九、結論

StayWise 的多語系設計將「語言」提升為系統核心：

• 靜態 UI 翻譯：保持一致性與可維護性。
• 動態資料翻譯：商業內容自然呈現多語版本。
• Filament 與 Livewire 整合：提供即時、可編輯的後台體驗。
• 權限與審計閉環：營運人員在任何語系下都能理解系統行為。

這套架構既適合中小型飯店快速上線，也能隨著租戶數量與功能擴充而水平擴展。

---