> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Locales e internacionalização

> Moeda, idioma da loja e traduções do tema — guia para agências e agentes de código.

Temas Corvex 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 expõe via `useLocalization()` / `storefront.shop.get()`. `moneyFormat` pode vir vazio. Nesse caso `formatMoney` usa `Intl`, não o template.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  useTranslation,
  useLocalization,
  formatPrice,
} from '@corvex/theme-sdk';
```

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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<span>{product.price.formatted}</span>
<span>{product.compareAtPrice?.formatted}</span>
<span>{cart.subtotalMoney?.formatted}</span>
```

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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex validate .
corvex pack .    # inclui locales.json se o arquivo existir em .corvex/
corvex publish .
```

**Não versionar** `.corvex/` no git.

***

## 5. Fluxo completo

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

***

## Próximos passos

* [Money (tipo)](https://docs-loja.usecorvex.com.br/data/resources/money.md)
* [SDK de temas](https://docs-loja.usecorvex.com.br/sdk/overview.md)
* [Arquitetura do tema](https://docs-loja.usecorvex.com.br/themes/structure.md)
* [Cookbook: cart drawer](https://docs-loja.usecorvex.com.br/cookbook/cart-drawer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.