@cactus-agents/i18n

SDK de internacionalizacao modular com selecao de idioma em build-time e suporte a overrides de fork. Baseado no i18next.

Instalacao

pnpm add @cactus-agents/i18n

Conceitos

Um idioma por build — sem language detector, sem fallback. O idioma e definido em build-time via env var (BRAND_LANGUAGE).
10 namespaces — cada dominio da plataforma tem seu proprio namespace de traducoes.
Fork overrides — marcas podem sobrescrever apenas as chaves que precisam via deepMerge. O restante mantem o valor do SDK.
Sem Suspense — evita flash de conteudo nao traduzido.
SSR/HMR safe — initI18n() e idempotente (nao reinicializa se ja foi chamado).

Uso basico

import { initI18n } from "@cactus-agents/i18n";

// Importar JSONs do idioma desejado
import common from "@cactus-agents/i18n/locales/pt-br/common.json";
import auth from "@cactus-agents/i18n/locales/pt-br/auth.json";
import countries from "@cactus-agents/i18n/locales/pt-br/countries.json";
import payments from "@cactus-agents/i18n/locales/pt-br/payments.json";
import games from "@cactus-agents/i18n/locales/pt-br/games.json";
import user from "@cactus-agents/i18n/locales/pt-br/user.json";
import validation from "@cactus-agents/i18n/locales/pt-br/validation.json";
import sports from "@cactus-agents/i18n/locales/pt-br/sports.json";
import gamification from "@cactus-agents/i18n/locales/pt-br/gamification.json";
import layout from "@cactus-agents/i18n/locales/pt-br/layout.json";

const i18n = initI18n({
  language: "pt-br",
  resources: {
    common,
    auth,
    countries,
    payments,
    games,
    user,
    validation,
    sports,
    gamification,
    layout,
  },
});

Com overrides de fork

const overrides = {
  common: { button: { save: "Gravar" } },
  layout: { header: { deposit: "Adicionar saldo" } },
};

const i18n = initI18n({
  language: "pt-br",
  resources: {
    common,
    auth,
    countries,
    payments,
    games,
    user,
    validation,
    sports,
    gamification,
    layout,
  },
  overrides,
});

Apenas as chaves fornecidas em overrides sao substituidas. Todas as outras mantem o valor original do SDK.

Fora do React

import { getI18n } from "@cactus-agents/i18n";

const i18n = getI18n();
const label = i18n.t("common:button.save");

API publica

Funcoes

Funcao	Descricao
`initI18n(options)`	Inicializa i18next com idioma, resources e overrides opcionais. Idempotente.
`getI18n()`	Retorna singleton i18next. Deve ser chamado apos `initI18n()`.
`deepMerge(base, override)`	Merge recursivo. Override sobrescreve apenas as chaves fornecidas.

Constantes

Constante	Valor
`TRANSLATION_NAMESPACES`	`["common", "auth", "countries", "payments", "games", "user", "validation", "sports", "gamification", "layout"]`

Tipos

Tipo	Descricao
`InitI18nOptions`	`{ language, resources, overrides? }`
`NamespaceResources`	`Record<string, Record<string, unknown>>`
`TranslationNamespace`	Union dos 10 nomes de namespace
`FullResources`	`Record<TranslationNamespace, Record<string, unknown>>`

Idiomas suportados

Codigo	Idioma	Diretorio
`pt-br`	Portugues (Brasil)	`locales/pt-br/`
`en`	Ingles	`locales/en/`
`es`	Espanhol	`locales/es/`

Namespaces

Namespace	Conteudo principal
`common`	Botoes, status, erros, tempo, paginacao, estados vazios
`auth`	Login, registro, esqueceu senha, reset password
`countries`	Nomes de paises e nacionalidades por ISO alpha-3
`payments`	Deposito, saque, PIX, SPEI, redirect, historico
`games`	Casino, busca, filtros, detalhes de jogo, stats, carrossel
`user`	Conta, carteira, seguranca, protecao, IRPF, notificacoes
`validation`	Steps de validacao (docs, endereco, telefone, email, KYC, limites, termos)
`sports`	Esportes, ao vivo, pre-match, apostas
`gamification`	VIP, missoes, torneios, loja, badges, mini-games, bonus, jackpots, raffles
`layout`	Header, sidebar, footer, mobile nav, busca, paginas de erro

Cada namespace e um arquivo JSON independente. Total: 30 arquivos (3 idiomas x 10 namespaces).

Import path dos locales

Os arquivos JSON podem ser importados diretamente via export path:

import common from "@cactus-agents/i18n/locales/pt-br/common.json";
import auth from "@cactus-agents/i18n/locales/en/auth.json";

Dependencias

Dependencia	Tipo
`i18next`	Runtime
`react`	Peer (opcional)
`react-i18next`	Peer (opcional)

React e react-i18next sao opcionais. O pacote funciona standalone em contextos Node/Worker.

Instalacao​

Conceitos​

Uso basico​

Com overrides de fork​

Fora do React​

API publica​

Funcoes​

Constantes​

Tipos​

Idiomas suportados​

Namespaces​

Import path dos locales​

Dependencias​