Internacionalizacao (i18n)

O template suporta multiplos idiomas com selecao em build-time. Apenas um idioma e incluido no bundle final.

Idiomas disponiveis

Codigo	Idioma
pt-br	Portugues (Brasil)
pt	Portugues (Portugal)
en	Ingles
en-ng	Ingles (Nigeria)
es	Espanhol
es-cl	Espanhol (Chile)
fi-fi	Finlandes

Esta e a lista dos locales publicados no @cactus-agents/i18n — a fonte de verdade e o diretorio locales/ do pacote.

Configuracao

Defina o idioma da marca na variavel de ambiente:

BRAND_LANGUAGE=pt-br

Isso determina qual conjunto de traducoes sera incluido no build.

cuidado

O valor precisa ser exatamente um dos codigos da tabela. A selecao de idioma acontece em build-time via alias: um codigo inexistente (ex: es-mx) nao resolve e o build falha. Se a sua marca precisa de um locale que nao esta na lista, fale com o time da plataforma — locales novos sao publicados no @cactus-agents/i18n, nao criados no fork.

Sobrescrevendo traducoes

Para personalizar textos sem alterar o SDK, crie arquivos de override. Diferente dos demais overrides do template, traducoes fazem deep-merge de chaves — voce declara so o que quer mudar, o resto vem do SDK.

1. Criar arquivo de override

O layout recomendado e por idioma:

app/locales/overrides/<lang>/<namespace>.json

Exemplo: app/locales/overrides/pt-br/common.json.

Arquivos direto na raiz (app/locales/overrides/common.json) tambem funcionam e sao tratados como agnosticos de idioma — uteis quando o texto vale pra qualquer locale.

2. Adicionar apenas as chaves que deseja alterar

{
  "button": {
    "save": "Gravar"
  }
}

3. Resultado

Apenas button.save sera sobrescrito. Todas as outras chaves mantem o valor original do SDK.

Ordem de precedencia

Do menor pro maior peso — o ultimo vence em caso de conflito:

1. Traducoes do @cactus-agents/i18n (base do SDK).
2. app/locales/overrides/<namespace>.json — agnostico de idioma.
3. app/locales/overrides/<lang>/<namespace>.json — especifico do BRAND_LANGUAGE ativo.
4. Overrides da marca (ver abaixo).

Overrides por marca

Um fork multi-marca pode ter traducoes proprias por marca. Crie:

overrides/<brand-key>/app/locales/brand-overrides.ts
overrides/<brand-key>/app/locales/overrides/<lang>/<namespace>.json

O brand-overrides.ts apenas exporta o glob dos JSONs vizinhos:

// overrides/<brand-key>/app/locales/brand-overrides.ts
export const brandOverrideModules = import.meta.glob<Record<string, unknown>>(
  ["./overrides/*.json", "./overrides/*/*.json"],
  { eager: true, import: "default" },
);

As chaves da marca fazem deep-merge por cima de tudo o que vem antes. O <brand-key> e derivado do ORIGIN_DOMAIN (minusculo, pontos viram hifens): minhamarca.com → minhamarca-com.

Namespaces disponiveis

Namespace	Descricao
common	Botoes, status, erros, paginacao
auth	Login, registro, esqueceu senha
countries	Nomes de paises e nacionalidades
payments	Deposito, saque, metodos de pagamento
casino	Cassino, busca, detalhes de jogo
user	Conta, carteira, seguranca
validation	Steps de validacao (email, telefone, KYC)
sports	Esportes, ao vivo, apostas
gamification	VIP, missoes, torneios, loja
layout	Header, sidebar, footer, navegacao
consent	Banner e preferencias de cookies
profiles	Paginas de perfil publico

Sao 12 namespaces hoje — cada um corresponde a um <namespace>.json dentro de locales/<lang>/ no @cactus-agents/i18n.

aviso

O namespace de cassino foi renomeado de games para casino. Se voce tem overrides em app/locales/overrides/games.json, renomeie o arquivo para casino.json.

Para nacionalidade no cadastro, use chaves em countries.nationalities.<ISO3> (ex: countries.nationalities.BRA).

Exemplo de override completo

Para uma marca em BRAND_LANGUAGE=pt-br que quer personalizar o header e os botoes:

app/locales/overrides/pt-br/layout.json:

{
  "header": {
    "deposit": "Adicionar saldo",
    "register": "Criar conta"
  }
}

app/locales/overrides/pt-br/common.json:

{
  "button": {
    "confirm": "Confirmar operacao",
    "cancel": "Voltar"
  }
}

Interpolacao

As traducoes suportam variaveis dinamicas:

{
  "greeting": "Ola, {{name}}!",
  "balance": "Saldo: {{currency}} {{value}}"
}

Pluralizacao

Chaves com _one e _other para pluralizacao automatica:

{
  "results_one": "{{count}} resultado",
  "results_other": "{{count}} resultados"
}