Localization

The Bridge SDK renders its secure fields with built-in copy — element labels, placeholders, and validation error messages. Localization lets you present that copy in your customer's language and tailor individual strings to match your product's voice, without touching the secure fields themselves.

The SDK ships with two built-in translation packs out of the box: English (en) and Brazilian Portuguese (pt-BR). You set a default locale once at initialization and, when you need finer control, override specific strings per element.

Setting the default locale

Pass locale to the SDK constructor to apply a language to every element you create. When omitted, the SDK defaults to 'en'.

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();

Overriding strings per element

Every element accepts its own locale and a translations object. Use this to localize a single field or to replace specific strings — a custom label, a friendlier error message — while leaving everything else on the built-in pack.

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');

Any string you do not override falls through to the built-in pack for the active locale. You only specify what you want to change.

Precedence

When the same string is defined in more than one place, the SDK resolves it from the most specific source first:

1. Per-element translations — passed to a create*Element() factory. Highest priority.
2. SDK-init translations — passed to the TokeflowBridge constructor. Applies to every element.
3. Built-in pack — the en or pt-BR strings shipped with the SDK. The fallback for anything not overridden.

Resolution is per string, not per object: a per-element override for one label does not discard your init-level override of a different label — each string is resolved independently down the chain.

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
  },
});

Example: overriding the card-number label and error in pt-BR

This example sets pt-BR as the default locale, then customizes the card-number element's label and its "invalid" error message. Every other string — the expiry placeholder, the CVC label, and so on — comes from the built-in pt-BR pack.

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

The same locale and translations props are available on the React element components.

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' },
        },
      }}
    />
  );
}

Set the default locale once on the provider so it applies to every element:

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

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

Inspecting the built-in packs

The built-in translation packs are exported as BUILTIN_TRANSLATIONS. Import it to see the exact shape and the strings each locale provides — useful when deciding which keys to override.

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

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

Related

• Quick Start — set up the SDK and mount your first element.
• Tokenization — exchange collected card data for a token reference.
• SDK Overview — the Bridge SDK at a glance.