본문으로 건너뛰기

다국어(i18n) 리소스 사용법 (syn.$res)

개요​

syn.$res(원본: context.$resource)는 화면에 표시되는 텍스트를 로케일별 번역 문자열로 치환하는 다국어(i18n) 기능을 제공합니다. HTML 엘리먼트에 syn-i18n 속성으로 번역 키를 지정하면, 페이지 로드 시 자동으로 스캔되어 번역 대상 목록(translateControls)에 등록되고, translations 저장소에 등록된 값으로 화면에 반영할 수 있습니다.

로드 방법​

syn.js가 로드되면 전역에 syn.$res(별칭: $resource)로 즉시 사용할 수 있습니다. [syn-i18n] 속성이 있는 엘리먼트는 페이지 로드가 완료된 시점(syn.$w.isPageLoad)에 자동으로 스캔되어 translateControls에 등록됩니다.

빠른 시작​

<div id="greetingText" syn-i18n="greeting">Hello</div>
syn.$res.add('greeting', '안녕하세요!');
syn.$res.translatePage();
// greetingText의 textContent가 '안녕하세요!'로 바뀝니다.

주요 시나리오​

syn-i18n 속성으로 번역 대상 지정​

syn-i18n 값이 단순 문자열이면 그 값이 번역 키(key)가 되고 bindSource는 기본값 'content'(textContent)로 처리됩니다. 객체 리터럴 문자열({key: '...', options: {...}}) 형태로 지정하면 options.bindSource로 text/content/html/url/placeholder/control/value 중 하나를 지정할 수 있습니다.

<div syn-i18n="greeting">Hello</div>
<input syn-i18n="{key: 'placeholderDemo', options: { bindSource: 'placeholder' }}" />

번역 데이터 등록/삭제​

add(id, val)로 번역 키-값을 translations 저장소에 등록하고, remove(id)로 제거합니다.

syn.$res.add('greeting', '안녕하세요, HandStack!');
syn.$res.remove('greeting');

화면 전체/개별 요소 번역 반영​

translatePage()는 등록된 모든 [syn-i18n] 요소를 현재 translations 값으로 갱신하고, translateElement(el, options)는 지정한 엘리먼트 하나만 갱신합니다. 내부적으로 getControl(el)로 컨트롤 설명 객체를 찾아 translateControl(control, options)을 호출하며, 실제 반영될 텍스트 계산은 translateText(control, options)가 담당합니다.

syn.$res.translatePage();
syn.$res.translateElement('greetingText');

플레이스홀더 치환​

interpolate(message, interpolations)는 #{key} 형태의 플레이스홀더가 포함된 문자열에서 interpolations 객체의 값으로 치환하는 순수 문자열 함수입니다. 화면 요소와 무관하게 단독으로 사용할 수 있습니다.

const text = syn.$res.interpolate('환영합니다, #{name}님!', { name: '홍길동' });

bindSource와 실제 DOM 속성 매핑​

getBindSource(control)은 control.bindSource(text/content/html/url/placeholder/control/value) 값을 실제 DOM 속성 이름(innerText/textContent/innerHTML/src/placeholder/controlText/value)으로 변환합니다.

실전 예제 페이지​

/sample/syn/resources.html 예제에서 다음 항목을 실습할 수 있습니다.

  • syn-i18n 속성이 지정된 content 바인딩 요소(demo_greeting), placeholder 바인딩 요소(demo_placeholder)
  • add(), remove(), interpolate() — 번역 데이터 등록/삭제/치환
  • getControl(), translatePage(), translateElement(), translateControl(), translateText(), getBindSource() — 컨트롤 조회와 화면 반영

주의 사항​

  • translateText(control, options)는 번역 문자열에 #{key} 형태의 플레이스홀더가 포함되어 있으면(정규식 매치 시) 무조건 syn.$w.getSSOInfo()를 호출합니다. 이 함수는 syn.domain.js(별도 모듈)에서 정의되며, syn.js만 로드하는 환경(이 샘플 포함)에서는 정의되어 있지 않아 TypeError가 발생할 수 있습니다. 플레이스홀더가 포함된 번역을 translatePage()/translateElement()/translateControl() 경로로 반영해야 한다면 syn.domain.js가 로드되어 있는지 먼저 확인하십시오. 화면 요소와 무관하게 단순 문자열만 치환하려면 interpolate()를 직접 사용하십시오(이 경로는 getSSOInfo()를 호출하지 않아 안전합니다).
  • setLocale(localeID)(비공개 목록 외 참고 메서드)는 syn.Config.LocaleAssetUrl 또는 SharedAssetUrl + 'language/' 경로에서 {localeID}.json 파일을 실제로 fetch합니다. 이 샘플 트리에는 해당 로케일 파일이 없으므로 실패하지만, 내부적으로 오류를 잡아(catch) Warning 로그만 남기고 페이지가 깨지지는 않습니다.
  • [syn-i18n] 스캔은 페이지 로드 완료 이후(syn.$w.readyAsync() resolve 시점) 수행되므로, 페이지 진입 직후 바로 getControl()을 호출하면 아직 등록되지 않았을 수 있습니다. 준비 완료를 기다리려면 await syn.$w.readyAsync()를 사용하십시오.

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭syn.$res (원본: context.$resource)
예제 페이지/sample/syn/resources.html
의존 모듈syn.$l(get, querySelector), syn.$object(isString, isNullOrUndefined, isObject, isArray), syn.$string(isNullOrEmpty, toBoolean), syn.$w(pageScript, argumentsExtend, fetchJson, getSSOInfo — getSSOInfo는 syn.domain.js에서만 정의됨), syn.uicontrols(모듈 컨트롤 번역 시)

속성​

이름기본값설명
localeID'ko-KR'현재 적용된 로케일 ID. setLocale() 호출 시 갱신됩니다.
fullyQualifiedLocale{ ko: 'ko-KR', en: 'en-US', ja: 'ja-JP', zh: 'zh-CN' }축약 언어 코드 → 정식 로케일 문자열 매핑 테이블.
translations{}add()/remove()로 관리되는 번역 키-값 저장소.
translateControls[]페이지 로드 시 [syn-i18n] 엘리먼트를 스캔하여 등록된 컨트롤 설명 배열. 각 항목은 { elID, key, bindSource, tag, module, type, options } 형태입니다.

메서드​

syn.$res.add(id, val)​

  • 설명: translations 저장소에 번역 키-값을 등록(덮어쓰기)합니다.
  • 매개변수
    이름타입필수설명
    idstringY번역 키.
    val문자열, 문자열 배열, Text 속성 객체Y번역 값. translateText()는 문자열, 배열의 첫 요소, Text 속성 객체 형태를 모두 처리합니다.
  • 반환값: 없음.
  • 예시 
    syn.$res.add('greeting', '안녕하세요, HandStack!');

syn.$res.remove(id)​

  • 설명: translations 저장소에서 지정 키를 삭제합니다.
  • 매개변수
    이름타입필수설명
    idstringY삭제할 번역 키.
  • 반환값: 없음.
  • 예시 
    syn.$res.remove('greeting');

syn.$res.interpolate(message, interpolations)​

  • 설명: message 문자열 내 #{key} 형태의 플레이스홀더를 interpolations 객체의 동일 키 값으로 치환합니다. 키별 정규식을 내부 캐시(interpolationRegexCache)에 보관하여 재사용합니다. 화면 요소와 무관한 순수 문자열 함수입니다.
  • 매개변수
    이름타입필수설명
    messagestringY플레이스홀더가 포함된 원본 문자열.
    interpolationsobjectY치환할 키-값 쌍.
  • 반환값: string — 치환된 문자열.
  • 예시 
    const text = syn.$res.interpolate('환영합니다, #{name}님!', { name: '홍길동' });

syn.$res.getControl(el)​

  • 설명: 엘리먼트(또는 id 문자열)로 translateControls 배열에서 대응하는 컨트롤 설명 객체를 찾습니다. el.id가 없으면 tag+i18n-key 조합으로, 있으면 elID+tag+i18n-key 조합으로 조회합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: object | null — 컨트롤 설명 객체({ elID, key, bindSource, tag, module, type, options }) 또는 찾지 못하면 undefined/null.
  • 예시 
    const control = syn.$res.getControl('demo_greeting');

syn.$res.translatePage()​

  • 설명: translateControls에 등록된 모든 컨트롤에 대해 translateControl()을 순회 호출하여 화면 전체를 현재 translations 값으로 갱신합니다.
  • 매개변수: 없음.
  • 반환값: 없음.
  • 예시 
    syn.$res.translatePage();

syn.$res.translateElement(el, options)​

  • 설명: 지정한 엘리먼트 하나에 대해서만 getControl() + translateControl()을 호출하여 번역을 반영합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
    optionsobjectNtranslateText()의 플레이스홀더 치환에 사용할 추가 값(내부적으로 getSSOInfo() 결과와 병합 시도).
  • 반환값: 없음. 대응하는 컨트롤이 없으면 아무 동작도 하지 않습니다.
  • 예시 
    syn.$res.translateElement('demo_greeting');

syn.$res.translateControl(control, options)​

  • 설명: 컨트롤 설명 객체를 받아 실제 DOM에 번역을 반영합니다. control.module이 없으면 getBindSource(control)로 얻은 DOM 속성(textContent 등)에 translateText() 결과를 대입하고, control.module이 있으면(UI 컨트롤 모듈) syn.uicontrols['$' + control.module].setLocale(...)을 호출합니다.
  • 매개변수
    이름타입필수설명
    controlobjectYgetControl()로 얻은 컨트롤 설명 객체.
    optionsobjectN플레이스홀더 치환용 추가 값.
  • 반환값: 없음.
  • 예시 
    const control = syn.$res.getControl('demo_greeting');
    syn.$res.translateControl(control);

syn.$res.translateText(control, options)​

  • 설명: control.key에 대응하는 translations 값을 조회하여 실제로 표시될 텍스트를 계산합니다(DOM에는 반영하지 않는 순수 계산). 번역 값이 문자열/배열(첫 요소)/{ Text } 객체인 경우를 모두 처리합니다. 텍스트에 #{key} 패턴이 있으면 syn.$w.getSSOInfo()를 호출해 기본 interpolation 값으로 사용하려 시도합니다.
  • 매개변수
    이름타입필수설명
    controlobjectYgetControl()로 얻은 컨트롤 설명 객체.
    optionsobjectNgetSSOInfo() 결과와 병합할 추가 interpolation 값.
  • 반환값: string — 계산된 표시 텍스트.
  • 주의: 텍스트에 #{key} 패턴이 포함되어 있으면 options 유무와 무관하게 syn.$w.getSSOInfo()가 무조건 호출됩니다. syn.js만 로드된 환경(syn.domain.js 미로드)에서는 이 함수가 정의되어 있지 않아 TypeError가 발생할 수 있습니다.
  • 예시 
    const control = syn.$res.getControl('demo_greeting');
    const text = syn.$res.translateText(control);

syn.$res.getBindSource(control)​

  • 설명: control.bindSource 값을 실제 DOM 속성 이름으로 매핑합니다.
  • 매개변수
    이름타입필수설명
    controlobjectYbindSource 속성을 가진 객체({ bindSource: 'text' | 'content' | 'html' | 'url' | 'placeholder' | 'control' | 'value' }).
  • 반환값: string | null — text→innerText, content→textContent, html→innerHTML, url→src, placeholder→placeholder, control→controlText, value→value. 매칭되지 않으면 null.
  • 예시 
    const prop = syn.$res.getBindSource({ bindSource: 'content' }); // 'textContent'

syn.$res.setLocale(localeID) (참고)​

  • 설명: 지정한 localeID의 로케일 JSON 파일(syn.Config.LocaleAssetUrl 또는 SharedAssetUrl + 'language/' 경로)을 fetch하여 translations에 병합한 뒤 document.documentElement.lang을 갱신하고 translatePage()를 호출하는 비동기 메서드입니다. 요청 대상 파일이 없거나 CORS 등으로 실패해도 내부적으로 예외를 잡아(Warning 로그) 페이지 동작에는 영향을 주지 않습니다. 이 문서의 필수 공개 API 목록에는 포함되지 않지만 소스 범위 내 실존하는 메서드로, 참고용으로 기재합니다.
  • 매개변수
    이름타입필수설명
    localeIDstringY적용할 로케일 ID(예: 'en-US').
  • 반환값: Promise<void>
  • 예시 
    await syn.$res.setLocale('en-US');