Locales e internacionalização

Temas Corvex V2 suportam vitrines internacionais com duas camadas separadas:

Camada	Quem define	O que controla
Loja (`shop.localization`)	Merchant / admin Corvex	Moeda, idioma ativo, `moneyFormat`
Tema (`locales/`)	Agência / dev do tema	Textos da UI, labels de sections/blocks

O SDK conecta as duas automaticamente. Não hardcode moeda nem strings de interface no código.

1. Configuração da loja (automática)

O JSON abaixo ilustra os campos de shop.localization que o SDK lê em GET /public/stores/{id}/shop. moneyFormat pode vir vazio. Nesse caso formatMoney usa Intl, não o template.

{
  "shop": {
    "localization": {
      "currency": "BRL",
      "language": "pt-br",
      "locales": [
        { "locale": "pt-br", "name": "Português (Brasil)", "primary": true }
      ],
      "currencies": ["BRL"],
      "moneyFormat": "R$ {{amount}}",
      "moneyFormatWithCurrency": "R$ {{amount}} BRL"
    }
  }
}

O SDK usa isso para:

formatar preços (product.price.formatted, carrinho, formatMoney)
escolher qual arquivo de locales/ carregar conforme language

Não leia shop.localization manualmente em sections — use os hooks abaixo.

2. Arquivos do tema (`locales/`)

Estrutura

locales/
├── pt-BR.default.json   # fallback quando o idioma da loja não casa com outro arquivo
├── en.json              # opcional
└── es.json              # opcional

O validador não exige a pasta locales/. Sem arquivo .default, o build não grava __defaultLocale e o SDK usa o primeiro catálogo que sobrar.

Convenção de nomes

Arquivo	Significado
`pt-BR.default.json`	Locale `pt-BR` e marcador de fallback (`__defaultLocale` no bundle)
`en.json`	Locale `en`
`en-US.json`	Locale `en-US`

O sufixo .default vira __defaultLocale. O SDK usa esse catálogo quando shop.localization.language não encontra arquivo, e também para chaves que faltam no idioma escolhido. A comparação ignora maiúsculas: pt-br casa com pt-BR.

Formato JSON

Chaves aninhadas com ponto na API de tradução:

{
  "cart": {
    "subtotal": "Subtotal",
    "add_to_cart": "Adicionar ao carrinho",
    "empty": "Seu carrinho está vazio"
  },
  "product": {
    "sold_out": "Esgotado",
    "add_to_cart": "Adicionar ao carrinho"
  },
  "sections": {
    "cart-page": { "name": "Carrinho" },
    "header": { "name": "Cabeçalho" }
  },
  "blocks": {
    "heading": { "name": "Título" }
  }
}

Recomendação de chaves:

Namespace	Uso
`cart.*`	Carrinho, drawer, checkout CTA
`product.*`	PDP, cards, variantes
`collection.*`	Listagens, filtros
`search.*`	Busca
`sections.{id}.*`	Textos da seção na vitrine
`blocks.{id}.*`	Textos do bloco na vitrine

Interpolação: {{variavel}} na string, passada no segundo argumento de t().

3. SDK — hooks e helpers

Import

import {
  useTranslation,
  useLocalization,
  formatPrice,
} from '@corvex/theme-sdk';

Traduções (`locales/` do tema)

export default function CartPageSection() {
  const { t } = useTranslation();

  return (
    <section>
      <h1>{t('sections.cart-page.name')}</h1>
      <p>{t('cart.empty')}</p>
      <button type="button">{t('cart.add_to_cart')}</button>
      <p>{t('search.no_results', { query: 'tênis' })}</p>
    </section>
  );
}

Hook / função	Fonte dos dados
`useTranslation()` → `t(key, vars?)`	Arquivos em `locales/` do tema
`useLocalization()` → `formatMoney`, `localization`	`shop.localization` da API

Moeda e preços

Preferir valores já formatados pela API:

<span>{product.price.formatted}</span>
<span>{product.compareAtPrice?.formatted}</span>
<span>{cart.subtotalMoney?.formatted}</span>

Formatação manual (quando só tem número):

const { formatMoney, localization } = useLocalization();

`formatMoney` do hook usa a localization da loja. `formatPrice(199)` sem o segundo argumento usa o padrão BRL do SDK. Passe `{ localization }` para acompanhar a loja.

4. Build e publish

corvex build .

Gera .corvex/locales.json a partir de locales/*.json. O runtime pede esse JSON em ?asset=locales. O log do corvex build só imprime a linha de locales quando o resultado da validação traz bundleLocales. O arquivo é gravado pelo build mesmo assim.

corvex validate .
corvex pack .    # inclui locales.json se o arquivo existir em .corvex/
corvex publish .

Não versionar .corvex/ no git.

5. Fluxo completo

Admin: language = "en", currency = "USD"
        ↓
SDK: storefront.shop.get() → cache localization
        ↓
ThemeLocaleProvider: carrega locales/en.json do tema
        ↓
t('cart.add_to_cart')     → "Add to cart"
product.price.formatted   → "$ 49.00"

6. Checklist para agências / LLMs

Criar locales/pt-BR.default.json quando a loja tiver textos de interface
Adicionar en.json (e outros) se a loja for multilíngue
Nenhum texto de UI hardcoded em português/inglês nas sections — usar t('...')
Preços sempre via .formatted ou formatMoney() — nunca "R$ " + price
Rodar corvex build . após alterar locales
Testar com loja em outro idioma/moeda no admin Corvex

7. Anti-patterns

Errado	Certo
`"R$ " + product.price.amount`	`product.price.formatted`
`formatPrice(99)` sem contexto em tema global	`formatMoney(99)` ou `.formatted`
Strings fixas `"Adicionar ao carrinho"`	`t('cart.add_to_cart')`
Traduções dentro do SDK / hardcoded no JSX	Arquivos em `locales/`
Inventar `shop.localization` fields	Usar hooks do SDK
Commitar `.corvex/locales.json`	Só `locales/*.json` no repo

8. Limitações e troubleshooting

Um idioma por loja — definido no admin; não há seletor /en/ na URL (ainda).
Chaves literais na UI (cart.add_to_cart em vez do texto): o artefato não tem catálogo de locales. Rode corvex build e envie o tema de novo. No dev, GET .../theme-bundle/...?asset=locales deve responder 200 com JSON.
Sections existentes precisam migrar strings para t() manualmente.

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Locales e internacionalização

Locales e internacionalização

1. Configuração da loja (automática)

2. Arquivos do tema (`locales/`)

Estrutura

Convenção de nomes

Formato JSON

3. SDK — hooks e helpers

Import

Traduções (`locales/` do tema)

Moeda e preços

4. Build e publish

5. Fluxo completo

6. Checklist para agências / LLMs

7. Anti-patterns

8. Limitações e troubleshooting

Próximos passos

​Locales e internacionalização

​1. Configuração da loja (automática)

​2. Arquivos do tema (locales/)

​Estrutura

​Convenção de nomes

​Formato JSON

​3. SDK — hooks e helpers

​Import

​Traduções (locales/ do tema)

​Moeda e preços

​4. Build e publish

​5. Fluxo completo

​6. Checklist para agências / LLMs

​7. Anti-patterns

​8. Limitações e troubleshooting

​Próximos passos

Locales e internacionalização

1. Configuração da loja (automática)

2. Arquivos do tema (`locales/`)

Estrutura

Convenção de nomes

Formato JSON

3. SDK — hooks e helpers

Import

Traduções (`locales/` do tema)

Moeda e preços

4. Build e publish

5. Fluxo completo

6. Checklist para agências / LLMs

7. Anti-patterns

8. Limitações e troubleshooting

Próximos passos