QuickUI 國際化 (i18n)

架支援直接設定語言內容或遠端載入語言檔案，並提供簡單的語言切換機制，使應用能夠適應不同語言環境的需求。

基本配置

  • i18n：包含各語言翻譯內容的物件或 JSON 路徑
  • i18nLang：預設顯示的語言代碼

i18n 配置

i18n: {
    語言代碼1: {
        // 直接定義語言內容
        key1: "值1",
        key2: "值2"
    },
    語言代碼2: "語言檔案路徑.json"  // 指定語言檔案路徑
}

每個語言代碼對應一個語言配置，可以是：

  • 物件格式：直接配置多語言內容
  • 字串格式：指定語言檔案（JSON）的路徑，框架將通過 fetch 動態載入

若為物件格式，直接配置多語言內容。

若為字串格式，會透過 fetch 動態載入語言檔案。

語言檔案格式

語言檔案採用 JSON 格式，包含鍵值對形式的翻譯內容：

{
    "key1": "值1",
    "key2": "值2",
    "nestedKey": {
        "subKey1": "子值1",
        "subKey2": "子值2"
    }
}

使用多語言內容

模板中使用

通過 i18n. 前綴來引用語言內容：

<h1>{{ i18n.greeting }}</h1>
<p>{{ i18n.messages.welcome }}</p>

程式中使用

在 JavaScript 中，可以通過 app.data.quickui_i18n 和 app.data.quickui_i18nLang 訪問語言配置：

// 獲取當前語言
const currentLang = app.data.quickui_i18nLang;

// 獲取特定語言的翻譯
const greeting = app.data.quickui_i18n[currentLang].greeting;

切換語言

提供了 lang() 方法用於切換顯示語言：

// 切換到英文
app.lang("en");

// 切換到中文
app.lang("zh");

調用 lang() 方法後，框架會：

  1. 將設定為指定的語言代碼
  2. 重新渲染頁面，更新所有使用 i18n. 的內容

完整範例

語言檔案 (en.json)

{
    "greeting": "Hello",
    "username": "Username"
}

HTML 模板與 JavaScript 代碼

<body id="app">
    <h1>{{ i18n.greeting }}, {{ i18n.username }}: {{ username }}</h1>
    <button @click="change" data-lang="zh">切換至中文</button>
    <button @click="change" data-lang="en">Switch to English</button>
</body>
<script>
const app = new QUI({
    id: "app",
    data: {
        username: "帕登"
    },
    i18n: {
        zh: {
        greeting: "你好",
        username: "用戶名"
        },
        en: "en.json",
    },
    i18nLang: "zh", // 選擇顯示語言
    event: {
        change: e => {
            const _this = e.target;
            const lang = _this.dataset.lang;
            app.lang(lang);
        },
    }
});
</script>

渲染結果 (i18nLang = "zh")

<body id="app">
    <h1>你好, 用戶名: 帕登</h1>
    <button data-lang="zh">切換至中文</button>
    <button data-lang="en">Switch to English</button>
</body>

渲染結果 (i18nLang = "en")

<body id="app">
    <h1>Hello, Username: 帕登</h1>
    <button data-lang="zh">切換至中文</button>
    <button data-lang="en">Switch to English</button>
</body>

進階用法

嵌套翻譯內容

語言檔案支援嵌套結構，方便組織複雜的翻譯內容：

{
    "nav": {
        "home": "Home",
        "about": "About",
        "contact": "Contact"
    },
    "messages": {
        "welcome": "Welcome to our website",
        "farewell": "Thank you for visiting"
    }
}

在模板中可以通過點符號訪問嵌套內容：

<nav>
    <a href="#home">{{ i18n.nav.home }}</a>
    <a href="#about">{{ i18n.nav.about }}</a>
    <a href="#contact">{{ i18n.nav.contact }}</a>
</nav>

動態語言內容

可以結合其他資料屬性使用語言配置：

<p>{{ i18n.welcome }}, {{ username }}!</p>

語言切換按鈕組

可以使用迴圈渲染創建語言切換按鈕組：

<div class="language-switcher">
    <button :for="(lang, name) in languages" @click="switchLang" :data-lang="lang">
        {{ name }}
    </button>
</div>
data: {
    languages: {
        "繁體中文": "zh-TW",
        "简体中文": "zh-CN",
        "English": "en",
        "日本語": "ja"
    }
},
event: {
    switchLang: e => {
        app.lang(e.target.dataset.lang);
    }
}

最佳實踐

  1. 語言代碼命名：使用標準的語言代碼，如 "en"、"zh-TW"、"zh-CN"、"ja" 等
  2. 組織翻譯內容：使用嵌套結構組織大型應用的翻譯內容
  3. 預設語言：始終設置一個預設語言，避免初始載入時沒有翻譯內容
  4. 遺漏翻譯：處理缺失翻譯的情況，可以顯示預設語言的翻譯或翻譯鍵本身
  5. 語言檔案分離：對於大型應用，將語言檔案分離存儲有助於管理和按需載入

技術細節

  • 語言切換時會重新渲染整個視圖，應用新的語言配置
  • 動態載入的語言檔案會被緩存在 app.data.quickui_i18n 中
  • 語言配置支援任意深度的嵌套結構
  • 對於缺失的翻譯，模板中的 {{ i18n.xxx }} 將顯示為空字串
English