현지화

mdui는 기본적으로 영어를 사용합니다. 다른 언어를 사용해야 하는 경우 다국어 구성이 필요합니다.

사용법

mdui는 다국어 기능을 구현하기 위해 세 가지 함수를 제공합니다:

• loadLocale: 언어 팩을 로드합니다. 매개변수는 함수이며, 언어 코드를 받아 Promise를 반환합니다. 언어 팩 로드가 완료되면 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에서 직접 편집할 수 있습니다.