버전 비교

Version 이전 버전 2 새 버전 3
변경한 사람

X2BEE 관리자

X2BEE 관리자

에 저장

키

  • 이 줄이 추가되었습니다.
  • 이 줄이 삭제되었습니다.
  • 서식이 변경되었습니다.

X2BEE BO(BackOffice)와 API 에서 메시지와 API의 메시지 처리 방법에 대해 설명합니다. 이를 통해 다국어 번역 처리 및 메시지 출력, 그리고 API에서 메시지를 동적으로 처리하는 방식에 대한 이해를 돕고, 실제 개발 환경에서의 활용 예시를 제공합니다.

...

BO 메시지 처리 방식 가이드

BO의 메시지는 ‘다국어 번역’ 및 ‘사용자 경험 개선’을 위해 설계되었습니다. 이 구조는 ‘reactreact-i18next’와 i18next와 상태 관리 라이브러리를 활용하여 동적이고 일관된 번역과 메시지 출력을 제공합니다.

1. allLangs 설정

다국어 번역 구조를 초기 설정합니다설정하는 내용으로, 각 언어에 대한 기본 설정을 정의합니다.

코드 블럭
languagejs
export const allLangs = [
  {
    value: 'en',
    label: 'English',
    countryCode: 'GB',
    adapterLocale: 'en',
    numberFormat: { code: 'en-US', currency: 'USD' },
    systemValue: { components: { /* 영어 설정 */ } },
  },
  {
    value: 'ko',
    label: 'Korea',
    countryCode: 'KR',
    adapterLocale: 'ko',
    numberFormat: { code: 'ko', currency: 'WON' },
    systemValue: { components: { /* 한국어 설정 */ } },
  },
]

...

2. useTranslate Hook

다국어 번역을 관리하는 커스텀 훅입니다훅으로, 언어 변경 처리 및 메시지 동기화 작업을 진행합니다.

코드 블럭
languagejs
export function useTranslate(
  ns?: string | string[], // 사용할 네임스페이스(다국어 번역 키 그룹)
  options: { keyPrefix?: KeyPrefix<string> } = {} // 키 프리픽스 설정
) {
  const router = useRouter();
  // react-i18next의 번역 함수 및 언어 정보
  const { t, i18n } = useTranslation(ns, options);
  // 공통 코드 동기화 함수
  const { updateCodeList } = useUpdateCommonCodeStore();
  // 기본 언어 설정
  const fallback = allLangs.find((lang) => lang.value === fallbackLng);
  const currentLang = allLangs.find(
    (lang) => lang.value === i18n.resolvedLanguage // 현재 설정된 언어 확인
  );
  const onChangeLang = useCallback(
    async (newLang: LanguageValue) => {
      try {
        // 언어 쿠키 저장
        setCookie('data_lang_cd', newLang);
        setCookie('lang_cd', newLang);
        // 언어 변경 시 공통 코드 동기화
        updateCodeList();
        // 언어 변경 처리
        const langChangePromise = i18n.changeLanguage(newLang);
        // 해당 언어 메시지 가져오기
        const currentMessages = messages[newLang] || messages.en;
        // 언어 변경 상태에 따른 사용자 피드백
        toast.promise(langChangePromise, {
          loading: currentMessages.loading,
          success: () => currentMessages.success,
          error: currentMessages.error,
        });
        // 날짜 로케일 동기화
        if (currentLang) dayjs.locale(currentLang.adapterLocale);
        // 페이지 새로고침으로 UI 갱신
        router.refresh();
      } catch (error) {
        console.error(error);
      }
    },
    [currentLang, i18n, router, updateCodeList]
  );
  return {
    t, // 번역 함수
    i18n, // 번역 엔진 상태
    onChangeLang, // 언어 변경 핸들러
    currentLang: currentLang ?? fallback, // 현재 언어
  };
}

사용법은 다음과 같습니다.

3. 메시지 JSON 작성

메시지 값은 src > /Locals > /langs 위치의 각 언어 폴더에 해당하는 메시지를 작성합니다 폴더 내 각 언어별 JSON 파일에 작성됩니다.

코드 블럭
languagejson
{
  "adminCommon": {
    "message": {
      "successfully": {
        "saved": "저장되었습니다.",
        "deleted": "삭제되었습니다."
      }
    }
  }
}

4. 페이지 및 컴포넌트에서의 사용 예시

실 화면에서 페이지와 컴포넌트에서 다국어 메시지를 사용하는 예시입니다.

코드 블럭
languagejs
const CM_NS = 'common';
const CM = { ns: CM_NS, keyPrefix: 'adminCommon' };
const sampleComponents = () => {
  const { t } = useTranslate([CM_NS]);
  const { dialogAlert } = useDialogContext();
  const onSave = () => {
    dialogAlert({
      text: t('message.successfully.saved', CM) // 저장되었습니다.
    });
  };
  // ...
};
export default sampleComponents;

...

API 메시지 처리 방식 가이드

메시지 값을 처리하기 위해 공통에서 MessageResolver 클래스를 제공합니다.X2BEE는 API에서의 메시지 처리 방법으로 MessageResolver 클래스를 제공합니다. 이를 통해 서버에서 필요한 메시지를 동적으로 처리하고, 호출한 서버의 상황에 맞게 메시지를 반환합니다.

1. MessageResolver.class

getLocaleMessage 함수가 메시지 값을 가져오는 주요 함수로서 다음과 같이 작동합니다.

...

messageKey 값이 String Key인 경우, 그대로 메시지 값을 반환합니다.

...

 함수는 메시지 키를 기반으로 메시지를 반환합니다. 서버가 BO-API인 경우, 해당 API에서 메시지를 반환하고, 그렇지 않으면 기본 메시지를 반환합니다.

코드 블럭
languagejava
private static String getLocaleMessage(AppError appError, Object[] args, Locale locale) {
    String message = "";
    if (RequestContextUtil.isCallServerBo()) { // 호출한 서버가 BO-API인API 호출 경우시
        message = getMessageKeyToMessageValue(appError.getBoMessageKey(), args, locale, false);
        if (StringUtils.isBlank(message)) {
   
        // BO-API 메시지 코드값이 없을 경우 기본 메시지 코드값 가져옴.
            message = getMessageKeyToMessageValue(appError.getMessageKey(), args, locale, true);
        }
    } else {
        message = getMessageKeyToMessageValue(appError.getMessageKey(), args, locale, true);
    }
    return message;
}

...

해당 enum class 파일에 code 값 및 message 키 값을 정의합니다정의하고, 서버에서 반환할 메시지 키를 관리합니ㅏㄷ.

코드 블럭
languagejava
public enum ApiError implements AppError {
    /* success */
    SUCCESS("0000", "common.message.success", "common.message.success", false),
    /* app error */
    EMPTY_PARAMETER("1001", "common.error.emptyParameter", "common.error.emptyParameter", false),
    INVALID_PARAMETER("1002", "common.error.invalidParameter", "common.error.invalidParameter", false),
    // unknown error
    UNKNOWN("9000", "common.error.unknown", "common.error.unknown"),
    // ValidationException error
    VALIDATION_EXCEPTION("9100", "common.error.unknown", "common.error.unknown"),
    TEST("9999", "event.aply.simple.member.limit.message", "event.aply.simple.member.limit.message.bo");
    
    private final String code;
    private final String messageKey;
    private final String boMessageKey;
}

...

event_ko.properties, event_en.properties 등 message properties 파일을 정리합니다. 해당 message properties 파일에 API에서 사용할 각 언어별로 메시지 값을 정의합니다.

코드 블럭
languageproperties
event.aply.simple.member.limit.message = 간편회원은 응모하실 수 없습니다.
event.aply.simple.member.limit.message2 = 간편회원은 응모하실 수 없습니다.

...