Internationalization (i18n)

TokenFlight includes built-in translations for five locales. Locale packs are lazy-loaded, so only the active language is fetched when needed.

Supported Locales

Code	Language
en-US	English (default)
zh-CN	Simplified Chinese (简体中文)
zh-TW	Traditional Chinese (繁體中文)
ja-JP	Japanese (日本語)
ko-KR	Korean (한국어)

Setting the Locale

Declarative

<tokenflight-widget
  locale="zh-CN"
  theme="dark"
  to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  trade-type="EXACT_OUTPUT"
  amount="100"
></tokenflight-widget>

Imperative

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    locale: 'ja-JP',
    theme: 'dark',
  },
});
widget.initialize();

Runtime Locale Changes

Locale is read during initialization. To switch languages after mount, destroy and recreate the widget:

widget.destroy();

const nextWidget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
    locale: 'zh-CN',
  },
});

nextWidget.initialize();

What Gets Translated

• Swap UI labels and actions
• Receive and card checkout copy
• Token selector text
• Error messages and status text
• Locale-aware number formatting

Text overrides (white-label)

Need to rename a handful of labels — "You pay" → "Amount", or match your product's vocabulary — without shipping a full translation? Pass textOverrides. Overrides apply on top of the active locale; unset keys fall back to the locale's default.

Keys are semantic (not i18n message IDs), so they stay stable across widget versions.

Declarative

import { registerWidgetElement } from '@tokenflight/swap/widget';

registerWidgetElement({
  textOverrides: {
    youPay: 'Amount',
    youReceive: 'Deposit',
  },
});

Imperative

import { setTextOverrides, TokenFlightWidget } from '@tokenflight/swap';

setTextOverrides({
  youPay: 'Amount',
  youReceive: 'Deposit',
});

const widget = new TokenFlightWidget({ container: '#widget', config: { /* ... */ } });
widget.initialize();

Call setTextOverrides(undefined) to clear.

Combine with a locale

Overrides apply on top of the active locale — so you can localize with locale: 'zh-CN' and still rename just one label:

registerWidgetElement({
  locale: 'zh-CN',
  textOverrides: { youPay: '充值金额' },
});

Override keys

The TextOverrides interface is small and fully typed — your editor will autocomplete every supported key:

interface TextOverrides {
  youPay?: string;     // default: "You pay"
  youReceive?: string; // default: "You receive"
}

Import the type directly if you need to type a config object:

import type { TextOverrides } from '@tokenflight/swap';

New keys are added as white-label deployments request them — see TypeScript Types for the canonical definition.