Habilidade de Localização
Esta skill orienta você na localização de lojas B2C Commerce para múltiplos idiomas e regiões.
Visão Geral
O B2C Commerce suporta localização através de:
| Componente | Abordagem |
|---|---|
| Templates | Conjunto único de templates + bundles de recursos |
| Formulários | Definições compartilhadas + rótulos específicos por localidade |
| Conteúdo estático | Pastas específicas por localidade |
| Dados de produto | Atributos localizáveis |
Formato de Localidade
As localidades seguem os padrões ISO: {idioma}_{país}
| Formato | Exemplo | Descrição |
|---|---|---|
en | Inglês | Apenas idioma |
en_US | Inglês/EUA | Idioma + país |
fr_CA | Francês/Canadá | Idioma + país |
de_DE | Alemão/Alemanha | Idioma + país |
Bundles de Recursos
Estrutura de Diretórios
/cartridge
/templates
/resources
account.properties # Padrão (Inglês)
checkout.properties
/fr
account.properties # Francês
checkout.properties
/de
account.properties # Alemão
checkout.properties
/fr_CA
account.properties # Francês Canadense
Formato do Arquivo de Propriedades
account.properties (padrão):
##############################################
# Páginas da Conta
##############################################
account.title=Minha Conta
account.greeting=Bem-vindo de volta
account.logout=Sair
# Painel de Controle
dashboard.title=Painel
dashboard.orders=Histórico de Pedidos
dashboard.addresses=Catálogo de Endereços
dashboard.wishlist=Lista de Desejos
# Perfil
profile.title=Perfil
profile.firstName=Nome
profile.lastName=Sobrenome
profile.email=Endereço de E-mail
profile.save=Salvar Alterações
account_fr.properties (Francês):
account.title=Mon compte
account.greeting=Bon retour
account.logout=Se déconnecter
dashboard.title=Tableau de bord
dashboard.orders=Historique des commandes
dashboard.addresses=Carnet d'adresses
dashboard.wishlist=Liste de souhaits
profile.title=Profil
profile.firstName=Prénom
profile.lastName=Nom
profile.email=Adresse e-mail
profile.save=Enregistrer les modifications
Usando Recursos em Templates
<!-- Mensagem simples -->
<h1>${Resource.msg('account.title', 'account', null)}</h1>
<!-- Com fallback -->
<p>${Resource.msg('account.greeting', 'account', 'Bem-vindo')}</p>
<!-- Com parâmetros -->
<p>${Resource.msgf('cart.items', 'cart', null, cartCount)}</p>
Parâmetros de Resource.msg():
- Nome da chave
- Nome do bundle (nome do arquivo sem extensão)
- Valor padrão (null = usa a chave se não encontrada)
Mensagens Parametrizadas
Propriedade:
cart.itemCount=Você tem {0} itens no seu carrinho
greeting.personalized=Olá, {0} {1}!
order.confirmation=Pedido #{0} realizado em {1}
Template:
${Resource.msgf('cart.itemCount', 'cart', null, itemCount)}
${Resource.msgf('greeting.personalized', 'common', null, firstName, lastName)}
Fallback de Localidade
O B2C Commerce usa uma cadeia de fallback: fr_CA → fr → padrão
Exemplo: Solicitando fr_CA:
- Procura em
/resources/fr_CA/account.properties - Se não encontrado, procura em
/resources/fr/account.properties - Se não encontrado, procura em
/resources/account.properties
Arquivos Estáticos
Estrutura de Diretórios
/cartridge
/static
/default
/css
style.css
/images
logo.png
buttons/
submit.png
/js
main.js
/fr
/images
buttons/
submit.png # Texto em francês no botão
/de
/images
buttons/
submit.png # Texto em alemão no botão
Referenciando Arquivos Estáticos
<!-- Usa a versão específica da localidade se disponível -->
<img src="${URLUtils.staticURL('/images/buttons/submit.png')}" alt="Enviar"/>
<!-- CSS (geralmente não localizado) -->
<link rel="stylesheet" href="${URLUtils.staticURL('/css/style.css')}"/>
Localização de Formulários
Definição do Formulário
<?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>
Bundle de Recursos
forms.properties:
form.email.label=Endereço de E-mail
form.email.required=E-mail é obrigatório
form.email.invalid=Por favor, insira um endereço de e-mail válido
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
Localização de URLs
URLs Conscientes da Localidade
<!-- URL da localidade atual -->
<a href="${URLUtils.url('Product-Show', 'pid', 'ABC123')}">Ver Produto</a>
<!-- URL de localidade específica -->
<a href="${URLUtils.url(new URLAction('Product-Show', 'MySite', 'fr'))}">
Voir le produit
</a>
Alternador de Idioma
<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>
Localização no Controlador
Acessando a Localidade Atual
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();
});
Lógica Específica por Localidade
server.get('Checkout', function (req, res, next) {
var locale = req.locale.id;
// Formato de data específico por localidade
var dateFormat = locale.startsWith('en_US') ? 'MM/dd/yyyy' : 'dd/MM/yyyy';
// Conteúdo específico por localidade
var termsContentId = 'terms-' + locale.replace('_', '-').toLowerCase();
res.render('checkout', {
dateFormat: dateFormat,
termsContentId: termsContentId
});
next();
});
Templates de E-mail
Definindo a Localidade
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();
}
Formatação de Moeda
A moeda está vinculada à localidade:
var Money = require('dw/value/Money');
var StringUtils = require('dw/util/StringUtils');
// Formatar com localidade
var price = new Money(99.99, 'USD');
var formatted = StringUtils.formatMoney(price); // Usa a localidade atual
// No template
<isprint value="${product.priceModel.price}" style="CURRENCY"/>
Formatação de Data
var StringUtils = require('dw/util/StringUtils');
var Calendar = require('dw/util/Calendar');
var date = new Calendar();
var formatted = StringUtils.formatCalendar(date, 'yyyy-MM-dd'); // Formato ISO
var localized = StringUtils.formatCalendar(date, 'MMMM d, yyyy'); // Consciente da localidade
Melhores Práticas
- Use UTF-8 para todos os arquivos de propriedades (necessário para caracteres não ASCII)
- Organize bundles por página/recurso, não por idioma
- Mantenha chaves descritivas -
account.profile.firstNamenãolabel1 - Use parâmetros para valores dinâmicos - não concatene strings
- Teste todas as localidades - garanta que o fallback funcione corretamente
- Não hardcode texto em templates ou scripts
Referência Detalhada
- Padrões de Localização - Padrões e exemplos completos