본문으로 건너뛰기

syn.$res

개요​

syn.$res는 HandStack 화면의 다국어 리소스와 텍스트 치환을 담당하는 리소스 모듈입니다. syn.js에서는 context.$resource = syn.$res = $resource로 공개되며, 화면 로딩 과정에서 syn-i18n 속성을 가진 컨트롤을 수집하고 locale 파일을 읽어 화면 텍스트를 적용합니다.

개발자가 알아야 할 구조​

항목설명
localeID현재 적용할 locale ID입니다. 기본값은 ko-KR입니다.
translationslocale key와 번역 값을 보관하는 객체입니다.
translateControlssyn-i18n 속성으로 수집된 화면 컨트롤 목록입니다.
setLocale(localeID)locale 파일을 읽고 화면 번역을 다시 적용합니다.
translatePage()수집된 모든 컨트롤에 번역을 적용합니다.
translateControl(control, options)특정 컨트롤 하나에 번역을 적용합니다.

HTML 작성 방식​

화면 요소에 syn-i18n 속성을 지정하면 syn.$res가 로딩 시 번역 대상으로 수집합니다.

<label id="lblName" syn-i18n="name"></label>
<button id="btnSave" syn-i18n="save"></button>
<input id="txtKeyword" syn-i18n="placeholder:searchKeyword" />

컨트롤별로 어떤 속성에 번역을 넣을지는 태그와 bind 규칙에 따라 결정됩니다. 일반 텍스트 요소는 텍스트 바인딩으로 처리하고, 입력 요소는 placeholder 같은 속성 바인딩을 사용할 수 있습니다.

리소스 등록과 조회​

syn.$res.add('save', '저장');
syn.$res.add('remove', '삭제');
syn.$res.add('welcome', '#{UserName}님, 환영합니다.');

const text = syn.$res.get('save');

기본 리소스에는 진행 중, 조회, 저장, 삭제, 필수 입력, 오류 메시지 같은 HandStack 화면 공통 문구가 등록되어 있습니다.

Locale 적용​

await syn.$res.setLocale('ko-KR');
syn.$res.translatePage();

setLocale은 syn.Config.LocaleAssetUrl이 있으면 그 경로를 우선 사용하고, 없으면 syn.Config.SharedAssetUrl + 'language/' 경로를 사용합니다. locale JSON을 읽은 뒤 기존 translations와 병합하고 화면을 다시 번역합니다.

화면 모듈 연동​

화면 모듈에 hook.pageResource가 있으면 locale 적용 과정에서 호출됩니다.

let $sample = {
    hook: {
        pageResource(localeID) {
            syn.$res.add('customMessage', localeID === 'ko-KR' ? '사용자 메시지' : 'User message');
        }
    }
};

syn.Config.IsLocaleTranslations가 true이고 화면 모듈의 config.isLocaleTranslations가 꺼져 있지 않으면 syn.$res.setLocale 흐름이 동작합니다.

텍스트 보간​

리소스 문자열에 #{Key} 형태를 사용하면 SSO 정보나 전달한 옵션으로 값을 치환할 수 있습니다.

syn.$res.add('helloUser', '#{UserName}님 안녕하세요.');
const message = syn.$res.translateText({ key: 'helloUser' }, { UserName: '홍길동' });

주의사항​

  • locale 파일 경로는 syn.Config.LocaleAssetUrl 또는 syn.Config.SharedAssetUrl에 의존합니다.
  • syn-i18n key가 중복되거나 누락되면 화면 로딩 로그에 경고가 남을 수 있습니다.
  • UI 컨트롤 모듈이 자체 locale 처리를 지원하면 controlModule.setLocale이 호출될 수 있으므로, 커스텀 컨트롤은 이 메서드 규약을 맞춰 구현합니다.
  • 화면별 문구는 화면 모듈의 hook.pageResource에서 보강하고, 공통 문구는 locale JSON 또는 기본 리소스에 둡니다.