현지화 스킬
이 스킬은 여러 언어와 지역에 맞게 B2C Commerce 스토어프론트를 현지화하는 방법을 안내합니다.
개요
B2C Commerce는 다음을 통해 현지화를 지원합니다:
| 구성 요소 | 접근 방식 |
|---|---|
| 템플릿 | 단일 템플릿 세트 + 리소스 번들 |
| 양식 | 공유 정의 + 로케일별 레이블 |
| 정적 콘텐츠 | 로케일별 폴더 |
| 제품 데이터 | 현지화 가능 속성 |
로케일 형식
로케일은 ISO 표준을 따릅니다: {language}_{country}
| 형식 | 예시 | 설명 |
|---|---|---|
en | 영어 | 언어만 |
en_US | 영어/미국 | 언어 + 국가 |
fr_CA | 프랑스어/캐나다 | 언어 + 국가 |
de_DE | 독일어/독일 | 언어 + 국가 |
리소스 번들
디렉토리 구조
/cartridge
/templates
/resources
account.properties # 기본값 (영어)
checkout.properties
/fr
account.properties # 프랑스어
checkout.properties
/de
account.properties # 독일어
checkout.properties
/fr_CA
account.properties # 프랑스어(캐나다)
속성 파일 형식
account.properties (기본값):
##############################################
# 계정 페이지
##############################################
account.title=내 계정
account.greeting=다시 오신 것을 환영합니다
account.logout=로그아웃
# 대시보드
dashoboard.title=대시보드
dashoboard.orders=주문 내역
dashoboard.addresses=주소록
dashoboard.wishlist=위시리스트
# 프로필
profile.title=프로필
profile.firstName=이름
profile.lastName=성
profile.email=이메일 주소
profile.save=변경 사항 저장
account_fr.properties (프랑스어):
account.title=Mon compte
account.greeting=Bon retour
account.logout=Se déconnecter
dashoboard.title=Tableau de bord
dashoboard.orders=Historique des commandes
dashoboard.addresses=Carnet d'adresses
dashoboard.wishlist=Liste de souhaits
profile.title=Profil
profile.firstName=Prénom
profile.lastName=Nom
profile.email=Adresse e-mail
profile.save=Enregistrer les modifications
템플릿에서 리소스 사용
<!-- 간단한 메시지 -->
<h1>${Resource.msg('account.title', 'account', null)}</h1>
<!-- 대체 값 포함 -->
<p>${Resource.msg('account.greeting', 'account', 'Welcome')}</p>
<!-- 매개변수 포함 -->
<p>${Resource.msgf('cart.items', 'cart', null, cartCount)}</p>
Resource.msg() 매개변수:
- 키 이름
- 번들 이름 (확장자를 제외한 파일명)
- 기본값 (null = 키를 찾을 수 없으면 키 사용)
매개변수화된 메시지
속성:
cart.itemCount=장바구니에 {0}개의 항목이 있습니다
greeting.personalized=안녕하세요, {0} {1}님!
order.confirmation=주문 #{0} (날짜: {1})
템플릿:
${Resource.msgf('cart.itemCount', 'cart', null, itemCount)}
${Resource.msgf('greeting.personalized', 'common', null, firstName, lastName)}
로케일 폴백
B2C Commerce는 폴백 체인을 사용합니다: fr_CA → fr → 기본값
예시: fr_CA 요청 시:
/resources/fr_CA/account.properties에서 찾기- 없으면
/resources/fr/account.properties에서 찾기 - 없으면
/resources/account.properties에서 찾기
정적 파일
디렉토리 구조
/cartridge
/static
/default
/css
style.css
/images
logo.png
buttons/
submit.png
/js
main.js
/fr
/images
buttons/
submit.png # 버튼에 프랑스어 텍스트
/de
/images
buttons/
submit.png # 버튼에 독일어 텍스트
정적 파일 참조
<!-- 로케일별 버전이 있으면 사용 -->
<img src="${URLUtils.staticURL('/images/buttons/submit.png')}" alt="제출"/>
<!-- CSS (보통 현지화되지 않음) -->
<link rel="stylesheet" href="${URLUtils.staticURL('/css/style.css')}"/>
양식 현지화
양식 정의
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
<field formid="email" label="form.email.label" type="string"
mandatory="true"
missing-error="form.email.required"
parse-error="form.email.invalid"/>
</form>
리소스 번들
forms.properties:
form.email.label=이메일 주소
form.email.required=이메일은 필수입니다
form.email.invalid=유효한 이메일 주소를 입력하세요
forms_fr.properties:
form.email.label=Adresse e-mail
form.email.required=L'email est requis
form.email.invalid=Veuillez entrer une adresse e-mail valide
URL 현지화
로케일 인식 URL
<!-- 현재 로케일 URL -->
<a href="${URLUtils.url('Product-Show', 'pid', 'ABC123')}">제품 보기</a>
<!-- 특정 로케일 URL -->
<a href="${URLUtils.url(new URLAction('Product-Show', 'MySite', 'fr'))}">
Voir le produit
</a>
언어 전환기
<isscript>
var Site = require('dw/system/Site');
var URLAction = require('dw/web/URLAction');
var URLUtils = require('dw/web/URLUtils');
var Locale = require('dw/util/Locale');
</isscript>
<ul class="language-switcher">
<isloop items="${Site.current.allowedLocales}" var="localeId">
<isscript>
var locale = new Locale(localeId);
var url = URLUtils.url(new URLAction('Home-Show', Site.current.ID, localeId));
</isscript>
<li class="${request.locale == localeId ? 'active' : ''}">
<a href="${url}">${locale.displayLanguage}</a>
</li>
</isloop>
</ul>
컨트롤러 현지화
현재 로케일 접근
var Locale = require('dw/util/Locale');
server.get('Show', function (req, res, next) {
var currentLocale = Locale.getLocale(req.locale.id);
res.render('mytemplate', {
locale: req.locale.id,
language: currentLocale.language,
country: currentLocale.country,
displayLanguage: currentLocale.displayLanguage,
displayCountry: currentLocale.displayCountry
});
next();
});
로케일별 로직
server.get('Checkout', function (req, res, next) {
var locale = req.locale.id;
// 로케일별 날짜 형식
var dateFormat = locale.startsWith('en_US') ? 'MM/dd/yyyy' : 'dd/MM/yyyy';
// 로케일별 콘텐츠
var termsContentId = 'terms-' + locale.replace('_', '-').toLowerCase();
res.render('checkout', {
dateFormat: dateFormat,
termsContentId: termsContentId
});
next();
});
이메일 템플릿
로케일 설정
var Template = require('dw/util/Template');
var HashMap = require('dw/util/HashMap');
var Mail = require('dw/net/Mail');
function sendOrderConfirmation(order, locale) {
var template = new Template('mail/orderconfirmation', locale);
var model = new HashMap();
model.put('order', order);
var content = template.render(model).text;
var mail = new Mail();
mail.addTo(order.customerEmail);
mail.setFrom('[email protected]');
mail.setSubject(Resource.msg('email.order.subject', 'email', null));
mail.setContent(content, 'text/html', 'UTF-8');
mail.send();
}
통화 형식 지정
통화는 로케일에 연결됩니다:
var Money = require('dw/value/Money');
var StringUtils = require('dw/util/StringUtils');
// 로케일로 형식 지정
var price = new Money(99.99, 'USD');
var formatted = StringUtils.formatMoney(price); // 현재 로케일 사용
// 템플릿에서
<isprint value="${product.priceModel.price}" style="CURRENCY"/>
날짜 형식 지정
var StringUtils = require('dw/util/StringUtils');
var Calendar = require('dw/util/Calendar');
var date = new Calendar();
var formatted = StringUtils.formatCalendar(date, 'yyyy-MM-dd'); // ISO 형식
var localized = StringUtils.formatCalendar(date, 'MMMM d, yyyy'); // 로케일 인식
모범 사례
- UTF-8 사용 - 모든 속성 파일에 대해 (비ASCII 문자 필수)
- 페이지/기능별로 번들 구성 - 언어별로 구성하지 마세요
- 키를 설명적으로 유지 -
label1대신account.profile.firstName - 동적 값에 매개변수 사용 - 문자열을 연결하지 마세요
- 모든 로케일 테스트 - 폴백이 올바르게 작동하는지 확인
- 템플릿이나 스크립트에 텍스트 하드코딩 금지
상세 참고
- 현지화 패턴 - 완전한 패턴 및 예제