Localização

O Bridge SDK renderiza seus campos seguros com textos integrados — rótulos de elementos, placeholders e mensagens de erro de validação. A localização permite que você apresente esses textos no idioma do seu cliente e ajuste strings individuais para combinar com a voz do seu produto, sem tocar nos campos seguros em si.

O SDK vem com dois pacotes de tradução integrados prontos para uso: Inglês (en) e Português do Brasil (pt-BR). Você define um locale padrão uma única vez na inicialização e, quando precisar de um controle mais refinado, substitui strings específicas por elemento.

Definindo o locale padrão

Passe locale ao construtor do SDK para aplicar um idioma a todos os elementos que você criar. Quando omitido, o SDK usa 'en' por padrão.

import { TokeflowBridge } from '@tokeflow_com/bridge-js';

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_live_mer_xxx',
  locale: 'pt-BR', // applies to every element by default
});

await tokeflow.init();

Substituindo strings por elemento

Todo elemento aceita seu próprio locale e um objeto translations. Use isso para localizar um único campo ou para substituir strings específicas — um rótulo personalizado, uma mensagem de erro mais amigável — deixando todo o resto no pacote integrado.

const cardNumber = tokeflow.createCardNumberElement({
  locale: 'pt-BR',
  translations: {
    number: {
      label: 'Número do cartão',
      errors: { invalid: 'Verifique o número do cartão' },
    },
  },
});

cardNumber.mount('#card-number');

Qualquer string que você não substituir recai sobre o pacote integrado do locale ativo. Você especifica apenas o que quer alterar.

Precedência

Quando a mesma string é definida em mais de um lugar, o SDK a resolve a partir da fonte mais específica primeiro:

1. translations por elemento — passado a uma factory create*Element(). Prioridade mais alta.
2. translations da init do SDK — passado ao construtor TokeflowBridge. Aplica-se a todos os elementos.
3. Pacote integrado — as strings en ou pt-BR que acompanham o SDK. O fallback para tudo o que não for substituído.

A resolução é por string, não por objeto: uma substituição por elemento para um rótulo não descarta a substituição de nível init de um rótulo diferente — cada string é resolvida de forma independente ao longo da cadeia.

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_live_mer_xxx',
  locale: 'pt-BR',
  translations: {
    // Applies to every element created from this bridge
    number: { label: 'Cartão de crédito' },
  },
});

await tokeflow.init();

// This element overrides the label again, just for itself
const cardNumber = tokeflow.createCardNumberElement({
  translations: {
    number: { label: 'Número do cartão' }, // wins for this element only
  },
});

Exemplo: substituindo o rótulo e o erro do número do cartão em pt-BR

Este exemplo define pt-BR como o locale padrão e depois personaliza o rótulo do elemento de número do cartão e sua mensagem de erro "invalid". Todas as outras strings — o placeholder de validade, o rótulo do CVC e assim por diante — vêm do pacote pt-BR integrado.

import { TokeflowBridge } from '@tokeflow_com/bridge-js';

const tokeflow = new TokeflowBridge({
  publicKey: 'pk_live_mer_xxx',
  locale: 'pt-BR',
});

await tokeflow.init();

const cardNumber = tokeflow.createCardNumberElement({
  locale: 'pt-BR',
  translations: {
    number: {
      label: 'Número do cartão',
      errors: {
        invalid: 'Verifique o número do cartão',
      },
    },
  },
});

const cardExpiry = tokeflow.createCardExpirationElement(); // built-in pt-BR
const cardCvc = tokeflow.createCardCvcElement();           // built-in pt-BR

cardNumber.mount('#card-number');
cardExpiry.mount('#card-expiry');
cardCvc.mount('#card-cvc');

React

As mesmas props locale e translations estão disponíveis nos componentes de elemento do React.

import { CardNumberElement } from '@tokeflow_com/bridge-js/react';

function CardNumber() {
  return (
    <CardNumberElement
      id="card-number"
      locale="pt-BR"
      translations={{
        number: {
          label: 'Número do cartão',
          errors: { invalid: 'Verifique o número do cartão' },
        },
      }}
    />
  );
}

Defina o locale padrão uma única vez no provider para que ele se aplique a todos os elementos:

import { TokeflowProvider } from '@tokeflow_com/bridge-js/react';

<TokeflowProvider config={{ publicKey: 'pk_live_mer_xxx', locale: 'pt-BR' }}>
  <YourApp />
</TokeflowProvider>;

Inspecionando os pacotes integrados

Os pacotes de tradução integrados são exportados como BUILTIN_TRANSLATIONS. Importe-o para ver a forma exata e as strings que cada locale fornece — útil ao decidir quais chaves substituir.

import { BUILTIN_TRANSLATIONS } from '@tokeflow_com/bridge-js';

console.log(BUILTIN_TRANSLATIONS.en);    // English pack
console.log(BUILTIN_TRANSLATIONS['pt-BR']); // Brazilian Portuguese pack

Relacionados

• Início rápido — configure o SDK e monte seu primeiro elemento.
• Tokenização — troque os dados do cartão coletados por uma referência de token.
• Visão geral do SDK — o Bridge SDK em resumo.