WebSquare5에서 다국어 처리를 적용할 때 localeRef 속성을 사용하면 UI 요소에 다국어 키에 해당하는 값이 표시됩니다.
그런데, 간혹 개발 환경이나 운영 환경에서 global_undefined 오류가 발생할 수 있는데요.
이번 포스팅에서는 WebSquare5 SP4 기준으로 해당 이슈의 원인과 해결 과정을 공유합니다.
문제 현상
- 버튼, 라벨 등 UI 요소에서 **global_undefined**가 출력됨
- localeRef에 키값을 정확히 지정했음에도 다국어 값이 표시되지 않음
- 언어 리소스(예: ko.js, en.js, 다국어 관리 테이블)는 정상적으로 로드된 상태
- 예시 XML 코드
<Trigger id="btnLogin" label="Login" localeRef="BTN_LOGIN" />
- 실행 결과(오류 발생)
[BTN_LOGIN] → global_undefined 출력
원인 분석
WebSquare5의 다국어 처리는 localeRef만으로는 완전하지 않습니다.
핵심 원인:
localeRef로 키를 매핑하더라도, 해당 컴포넌트에 useLocale="true" 속성이 누락되면 다국어 변환이 일어나지 않습니다.
그러면 왜 이런 일이 발생했을까?
원인을 분석해보자면..
1. SP4 디자인 탭에서는 useLocale 속성이 UI상에 노출되지 않음
2. 따라서 기존 개발자가 localeRef만 설정하고 넘어갔을 가능성 높음
3. 결과적으로 다국어 처리가 무시되며 global_undefined가 출력됨
해결 방법
디자인 모드로는 설정이 어렵기 때문에 XML Viewer에서 직접 수정해야 합니다.
1. XML 소스 열기
:WebSquare5 화면 편집기에서 XML 탭으로 전환
2. 컴포넌트 수정
:localeRef 속성이 설정된 컴포넌트를 찾아 useLocale="true" 속성을 추가합니다.
수정 전
<Trigger id="btnLogin" label="Login" localeRef="BTN_LOGIN" />
수정 후
<Trigger id="btnLogin" label="Login" localeRef="BTN_LOGIN" useLocale="true" />
3. 저장 및 확인(필수)
파일 저장 후 페이지를 새로 고침하거나 실행하여 global_undefined 가 아닌 정상적인 텍스트가 출력되는지 확인합니다.
적용 결과
정상 출력 예시:
다국어 파일에 BTN_LOGIN = 로그인 (ko), BTN_LOGIN = Login (en)로 정의된 경우
브라우저 언어 또는 시스템 설정에 따라 "로그인" 또는 "Login"으로 정상 표시됨
마무리: 실무 팁
다국어 적용 시 반드시 useLocale도 함께 확인할 것
디자인 모드에 없는 속성은 XML에서 직접 수정하는 습관 들이기
언어 키가 정상인데도 global_undefined가 뜬다면:
1. useLocale 누락 여부
2. 언어 파일 로드 여부
3. locale 키 오타 여부