Localization

Localization changes how SDK-owned UI is read. It does not rewrite market data, infer exchange schedules, or translate host-owned content.

Locale owns words and number/date formatting; display timezone owns how absolute timestamps are labeled; the symbol schedule still owns market-session boundaries.

Choose the setting by outcome

You need to change	Use	Does not change
SDK labels and messages	locale, loadLocales, translations, translate	Host content or market data
Date/time string shape	formatters	The instant represented
Decimal and grouping separators	numericFormatting	Symbol tick precision or price value
Axis/crosshair display zone	timezone	Bar timestamps
Friendly timezone entries	timezoneAliases	The resolved IANA zone
Exchange session zone	SymbolInfo.timezone or schedule timezone	User display preference

Resolution order

Each layer has one owner: the default English and zh-CN catalogs ship with the SDK; host-supplied catalogs arrive through loadLocales(locale, catalog) and per-chart translations; runtime updates come from the translate hook and setLocale / setLocalization calls.

Each layer overrides only the keys it supplies. Missing or unknown locale keys fall back to English. Host-rendered strings remain host-owned.

Before and after: three real strings

The market-status popover renders built-in keys. Default (en-US catalog):

Key	Rendered text	Source layer
market_status_symbol	Symbol	Default catalog
market_status_updated	Updated	Default catalog
market_status_close_details	Close market status details	Default catalog

The host registers a partial French catalog and switches the locale:

import { loadLocales } from '@tradescript/pro/sdk';

loadLocales('fr-FR', {
  market_status_symbol: 'Symbole',
  market_status_updated: 'Mis a jour',
});

chart.customization().setLocale('fr-FR');

After:

Key	Rendered text	Source layer
market_status_symbol	Symbole	Host catalog (loadLocales)
market_status_updated	Mis a jour	Host catalog (loadLocales)
market_status_close_details	Close market status details	English fallback (key missing from fr-FR)

The last row is the missing-key fallback: a locale catalog may be partial, and any key it lacks resolves per key to the en-US string — and only if English also lacked it, to the raw key text. Switching to a locale with no registered catalog at all logs a one-time console warning (Locale 'x' has no registered catalog; falling back to en-US.) and renders English. A later runtime call — translations or translate on setLocalization — overrides any of these rows on that chart only.

Minimal chart localization

import { loadLocales } from '@tradescript/pro/sdk';

loadLocales('fr-FR', {
  confirm: 'Confirmer',
  market_status_symbol: 'Symbole',
  market_status_updated: 'Mis a jour',
});

chart.customization().setLocale('en-US');
chart.customization().setTimezone('America/New_York');

chart.customization().setLocalization({
  locale: 'fr-FR',
  timezone: 'Europe/Paris',
  translations: {
    confirm: 'Confirmer',
    market_status_close_details: 'Fermer les details du statut du marche',
  },
  translate(key, context) {
    if (key === 'timezone') return `${context.defaultText} locale`
    return undefined
  },
  formatters: {
    date: 'DD/MM/YYYY',
    time: 'HH:mm',
    dateTime: 'DD/MM/YYYY HH:mm',
  },
  numericFormatting: {
    decimalSign: ',',
    groupSeparator: '.',
    groupSize: 3,
    secondaryGroupSize: 2,
  },
});

loadLocales(locale, catalog) registers shared SDK text. LocalizationSettings.translations adds chart-instance overrides without mutating that catalog. translate(key, context) is the final chart-level hook; return undefined or null to keep the resolved fallback.

Object Tree, properties dialogs, comparison, storage, trading ticket, depth, order-flow, session badge, Data Window, News, Instrument Details, Watchlist, and workspace controls all use this resolver. Per-widget labels remain the last, narrowest override for that widget instance.

Related helpers from @tradescript/pro/sdk: getSupportedLocales() returns every locale with a registered catalog, getLocaleKeys() returns the full built-in key list (the authoring checklist for a new language), and isRtlLocale(locale) reports whether UI chrome should lay out right-to-left.

Verification

1. Switch to the target locale and inspect one toolbar, one modal, one empty state, and one error state.
2. Confirm an intentionally missing key falls back to English rather than showing the key id or a blank label.
3. Verify a price still follows SymbolInfo.priceFormat while a plain numeric field uses the chosen decimal/group separators.
4. Switch display timezone and verify only rendered time labels move.
5. Reload restored chart state and confirm the documented locale/timezone persistence owner wins.

Next steps

• Timezones — timestamp and schedule ownership across exchange, chart, browser, and session zones.
• Accessibility Validation — the release-ready language and assistive-technology check.
• Themes — the visual layer that composes with these localization settings.