Localization

mdui uses English by default. If you wish to use other languages, you'll need to do some localization configuration.

Usage

mdui provides three functions for localization:

• loadLocale: Loads locale modules. Accepts a function that takes a locale code and returns a Promise resolving to the locale module. Ensure to call this function in your project's entry file.
• setLocale: Begins switching the active locale to the given locale code, and returns a promise that resolves when 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 locale, and returns a promise that resolves when 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 occured, 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

Start pre-loading all locales when the page loads. Dynamic imports are still used to ensure that the remaining script on the page is not blocked while the locale modules are being fetched.

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

Use static imports to pre-load all locales in a way that blocks other script on the page.

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 if you don’t want to clone the repo locally.