在地化

mdui 內部預設使用英文，如果要使用其他語言，則需要進行多語言設定。

使用方法

mdui 提供三個函式來實作多語言功能：

• loadLocale：載入語言包。參數為一個函式，接收一個語言代碼作為參數，回傳 Promise，語言包載入完成時會 resolve 為對應的語言包。請確保在專案進入點呼叫該函式。
• setLocale：切換到指定的語言。參數為新的語言代碼，回傳 Promise，在新的語言包載入完成後會 resolve。
• getLocale：取得目前的語言代碼。

範例如下：

import { loadLocale } from 'mdui/functions/loadLocale.js';
import { setLocale } from 'mdui/functions/setLocale.js';
import { getLocale } from 'mdui/functions/getLocale.js';

// 在專案進入點處呼叫 loadLocale 載入語言包
loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`));

// 在需要切換語言時呼叫該函式。在 Promise resolve 後，語言切換成功
setLocale('zh-cn').then(() => {
  // 呼叫 getLocale 可取得目前的語言代碼
  console.log(getLocale()); // zh-cn
});

狀態事件

在語言切換開始、結束、失敗時，會在 window 上觸發 mdui-localize-status 事件，你可以監聽該事件來執行自訂操作，例如在語言切換成功後將語言代碼寫入 Cookie。

事件的detail.status 屬性描述了目前發生何種狀態的變更，可能的值包括：loading、ready、error：

範例如下：

window.addEventListener('mdui-localize-status', (event) => {
  if (event.detail.status === 'loading') {
    console.log(`開始載入新的語言包：${event.detail.loadingLocale}`);
  } else if (event.detail.status === 'ready') {
    console.log(`新語言包 ${event.detail.readyLocale} 載入成功`);
  } else if (event.detail.status === 'error') {
    console.error(
      `新語言包 ${event.detail.errorLocale} 載入失敗：${event.detail.errorMessage}`,
    );
  }
});

語言包載入方式

延遲載入

使用動態引入可以在切換到對應語言時，才下載對應的語言包。這是最為推薦的方法。

import { loadLocale } from 'mdui/functions/loadLocale.js';

loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`));

預載入

在頁面載入時先預先下載所有需要的語言包。這樣在切換語言時就不必重新下載，切換也會更快。

import { loadLocale } from 'mdui/functions/loadLocale.js';

const localizedTemplates = new Map([
  ['zh-cn', import(`../node_modules/mdui/locales/zh-cn.js`)],
  ['zh-tw', import(`../node_modules/mdui/locales/zh-tw.js`)],
]);

loadLocale(async (locale) => localizedTemplates.get(locale));

靜態引入

使用此方法可將所有需要的語言包與專案程式碼打包成同一個檔案，不必另外下載語言包。

import { loadLocale } from 'mdui/functions/loadLocale.js';
import * as locale_zh_cn from 'mdui/locales/zh-cn.js';
import * as locale_zh_tw from 'mdui/locales/zh-tw.js';

const localizedTemplates = new Map([
  ['zh-cn', locale_zh_cn],
  ['zh-tw', locale_zh_tw],
]);

loadLocale(async (locale) => localizedTemplates.get(locale));

透過 CDN 載入語言包

如果你是透過 CDN 使用 mdui，可以直接從 CDN 載入語言包。範例如下：

<script src="https://unpkg.com/mdui@2/mdui.global.js"></script>

<script>
  mdui.loadLocale(
    (locale) => import(`https://unpkg.com/mdui@2/locales/${locale}.js`),
  );
  mdui.setLocale('zh-cn');
</script>

支援的語言

目前，mdui 支援以下語言：

提交新的翻譯

要貢獻新的翻譯、或對現有翻譯進行改進，請在 GitHub 上發起一個 Pull Request。語言包位於 packages/mdui/src/xliff，你可以直接在 GitHub 上進行編輯。