Локализация

В mdui по умолчанию используется английский язык. Для использования других языков требуется настройка локализации.

Использование

mdui предоставляет три функции для реализации локализации:

• loadLocale: загружает языковой пакет. Параметр — функция, которая получает код языка и возвращает Promise, который разрешается (resolve) в соответствующий языковой пакет. Вызовите эту функцию в точке входа вашего приложения.
• setLocale: переключает на указанный язык. Параметр — новый код языка, возвращает Promise, который разрешается после завершения загрузки языкового пакета.
• 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 разрешится после успешного переключения
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

Если вы используете mdui через CDN, вы можете загружать языковые пакеты непосредственно из 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 поддерживает следующие языки:

Добавление нового перевода

Чтобы добавить новый перевод или улучшить существующий, создайте Pull Request на Github. Языковые пакеты находятся в packages/mdui/src/xliff. Вы можете редактировать их прямо на Github.