Localization

mdui defaults to English. To support other languages, configure localization.

Usage

mdui provides three functions for localization:

• loadLocale: Loads locale modules. Accepts a loader function that takes a locale code and returns a Promise that resolves to the matching locale module. Call this function in your project's entry file.
• setLocale: Starts switching to the given locale code and returns a promise that resolves once the new locale has loaded.
• getLocale: Returns the active locale code.

Example usage:

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

// Load locale modules in the entry point of your project
loadLocale((locale) => import(`../node_modules/mdui/locales/${locale}.js`));

// Switch the locale and return a promise that resolves once the new locale has loaded
setLocale('zh-cn').then(() => {
  // You can use getLocale() to get the current locale code
  console.log(getLocale()); // zh-cn
});

Status Events

The mdui-localize-status event fires on window whenever a locale switch starts, finishes, or fails. You can listen to this event to execute custom operations, such as setting a locale preference cookie.

The detail.status string property tells you what kind of status change has occurred, and can be either loading, ready, or error:

Example of using the status event:

window.addEventListener('mdui-localize-status', (event) => {
  if (event.detail.status === 'loading') {
    console.log(`Loading new locale: ${event.detail.loadingLocale}`);
  } else if (event.detail.status === 'ready') {
    console.log(`Loaded new locale: ${event.detail.readyLocale}`);
  } else if (event.detail.status === 'error') {
    console.error(
      `Error loading locale ${event.detail.errorLocale}: ${event.detail.errorMessage}`,
    );
  }
});

Approaches for loading locale modules

Lazy-load

Use dynamic imports to load each locale only when it becomes active. This is a good default because it minimizes the amount of code that your users will download and execute.

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

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

Pre-load

Download all required locale modules when the page loads. This eliminates additional downloads when switching languages, making language switching faster.

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));

Static imports

This method bundles all required locale modules into the same file as your project code, eliminating the need for separate locale downloads.

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));

Loading Locale Modules via CDN

When using mdui via CDN, you can directly load locale modules from the 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>

Supported Languages

mdui supports the following locales:

Submitting New Translations or Improvements

To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in packages/mdui/src/xliff and can be edited directly on GitHub.