ローカライズ

mdui はデフォルトで英語を使用します。他の言語を使用する場合は、ローカライズ設定を行う必要があります。

使用方法

mdui はローカライズ機能を実現するために 3 つの関数を提供しています：

• loadLocale：言語パックをロードします。パラメーターは関数で、言語コードを受け取り、Promise を返します。言語パックのロードが完了すると、Promise は対応する言語パックで解決されます。プロジェクトのエントリーファイルでこの関数を呼び出してください。
• 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}`,
    );
  }
});

言語パックのロード方法

遅延ロード（Lazy Load）

動的インポート を使用すると、対応する言語に切り替えたときにのみ、対応する言語パックがダウンロードされます。これが最も推奨される方法です。

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 上で直接編集できます。