@luxalgo/vela 0.8.5 → 0.9.1

package/dist/{chunk-AUOB7A5Y.js → chunk-WHPQQYH7.js}

@@ -1,5 +1,5 @@
-import { normalizeProps, nextUid, runMachine, spreadProps } from './chunk-WY5H4S4I.js';
-import { injectStyles, holdForExit, announceSurface } from './chunk-I2U4NZD2.js';
+import { normalizeProps, nextUid, runMachine, spreadProps } from './chunk-PZN4RS4T.js';
+import { msg, textOf, injectStyles, holdForExit, announceSurface } from './chunk-O6L27KRB.js';
 import * as tooltip from '@zag-js/tooltip';
 import * as dialog from '@zag-js/dialog';
 
@@ -16,7 +16,15 @@ var KEY_ALIASES = {
   up: "arrowup",
   down: "arrowdown"
 };
-var MAC_GLYPHS = { meta: "\u2318", ctrl: "\u2303", alt: "\u2325", shift: "\u21E7" };
+var MAC_GLYPHS = { meta: "⌘", ctrl: "⌃", alt: "⌥", shift: "⇧" };
+var KEY_TEXT = {
+  ctrl: msg("ui.keys.ctrl", "Ctrl"),
+  alt: msg("ui.keys.alt", "Alt"),
+  shift: msg("ui.keys.shift", "Shift"),
+  meta: msg("ui.keys.meta", "Win"),
+  space: msg("ui.keys.space", "Space"),
+  general: msg("ui.keys.general", "General")
+};
 function parseChord(spec, mac) {
   const parts = spec.toLowerCase().split("+").map((p) => p.trim()).filter((p, i, a) => p !== "" || a[i - 1] === "");
   const chord = { ctrl: false, meta: false, alt: false, shift: false, key: "" };
@@ -31,10 +39,16 @@ function parseChord(spec, mac) {
   }
   return chord;
 }
+function chordKeyOf(ev) {
+  const key = String(ev.key ?? "").toLowerCase();
+  if (key.length !== 1 || /^[a-z0-9]$/.test(key) || !/\p{L}/u.test(key)) return key;
+  const m = /^Key([A-Z])$|^Digit([0-9])$/.exec(ev.code ?? "");
+  return m ? (m[1] ?? m[2]).toLowerCase() : key;
+}
 function eventMatches(ev, c) {
   return ev.ctrlKey === c.ctrl && ev.metaKey === c.meta && ev.altKey === c.alt && // Shift is part of producing many printable keys ('?', '+') — only enforce it
   // when the chord names a non-printable/letter key where shift is a real modifier.
-  (c.key.length > 1 || /^[a-z0-9 ]$/.test(c.key) ? ev.shiftKey === c.shift : true) && ev.key.toLowerCase() === c.key;
+  (c.key.length > 1 || /^[a-z0-9 ]$/.test(c.key) ? ev.shiftKey === c.shift : true) && chordKeyOf(ev) === c.key;
 }
 function isEditableTarget(ev) {
   const t = ev.target;
@@ -44,13 +58,14 @@ function isEditableTarget(ev) {
   if (t.isContentEditable === true) return true;
   return (typeof t.getAttribute === "function" ? t.getAttribute("role") : null) === "textbox";
 }
-function displayChord(spec, mac) {
+function displayChord(spec, mac, i18n) {
   const c = parseChord(spec, mac);
-  const keyLabel = c.key === " " ? "Space" : c.key.length === 1 ? c.key.toUpperCase() : c.key.charAt(0).toUpperCase() + c.key.slice(1);
+  const name = (m) => textOf(i18n, m);
+  const keyLabel = c.key === " " ? name(KEY_TEXT.space) : c.key.length === 1 ? c.key.toUpperCase() : c.key.charAt(0).toUpperCase() + c.key.slice(1);
   if (mac) {
     return (c.ctrl ? MAC_GLYPHS.ctrl : "") + (c.alt ? MAC_GLYPHS.alt : "") + (c.shift ? MAC_GLYPHS.shift : "") + (c.meta ? MAC_GLYPHS.meta : "") + keyLabel;
   }
-  const mods = [c.ctrl && "Ctrl", c.alt && "Alt", c.shift && "Shift", c.meta && "Win"].filter(Boolean);
+  const mods = [c.ctrl && name(KEY_TEXT.ctrl), c.alt && name(KEY_TEXT.alt), c.shift && name(KEY_TEXT.shift), c.meta && name(KEY_TEXT.meta)].filter(Boolean);
   return [...mods, keyLabel].join("+");
 }
 var KeymapManager = class {
@@ -81,17 +96,18 @@ var KeymapManager = class {
     if (keys === null) this.rebinds.delete(id);
     else this.rebinds.set(id, Array.isArray(keys) ? [...keys] : [keys]);
   }
-  /** Snapshot for a shortcuts help panel / rebinding UI. */
-  bindings() {
+  /** Snapshot for a shortcuts help panel / rebinding UI: labels, categories and key
+   *  names in `i18n`'s language (English when absent). */
+  bindings(i18n) {
     return [...this.descriptors.values()].map((d) => {
       const keys = this.activeKeys(d);
       return {
         id: d.id,
-        label: d.label,
-        category: d.category ?? "General",
+        label: textOf(i18n, d.label),
+        category: textOf(i18n, d.category ?? KEY_TEXT.general),
         scope: d.scope ?? this.baseScope,
         keys,
-        display: keys.map((k) => displayChord(k, this.mac))
+        display: keys.map((k) => displayChord(k, this.mac, i18n))
       };
     });
   }
@@ -252,7 +268,7 @@ var DRAWER_CSS = `
     z-index: var(--vela-z-dialog);
 }
 /* Inside a shell that declares a size class, the sheet scopes to the SHELL's bounds
-   (the widget root is position:relative) instead of the whole viewport \u2014 an embedded
+   (the widget root is position:relative) instead of the whole viewport — an embedded
    chart must not curtain the host page. */
 [data-layout] .vela-drawer-backdrop, [data-layout] .vela-drawer-positioner { position: absolute; }
 .vela-drawer {

package/dist/{contributions-D8xuYc9U.d.cts → contributions-BfBaF6eE.d.ts}

@@ -1,5 +1,6 @@
-import { x as Millis, ao as InputSchema, am as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, aH as PaneAxis, a_ as SeriesSpec, ak as Fill, H as Background, aQ as PriceLine, a7 as DrawingLine, a3 as DrawingBox, a6 as DrawingLabel, ab as DrawingPolyline, a8 as DrawingLinefill, ag as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, z as DrawingTypeKey, y as SnapMode, a9 as DrawingMode, u as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, r as ClickEvent, A as AxisLongPressEvent, v as DataWindowReadout, n as SymbolPickerFn, W as WallClock, bg as PaneInfo, aj as DrawingsOption, ad as DrawingSeriesGateway, bh as DrawingToolDefaults, bi as DrawingToolTemplate, D as Drawing, s as TimelineMark, t as MarkGroup, b as VelaOptions, F as AddIndicatorOptions, aG as MarketSwitch, E as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BI5Tp32b.cjs';
-import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-DdqMxKdl.cjs';
+import { y as Millis, aq as InputSchema, an as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, m as IndicatorModel, l as MoveTarget, aJ as PaneAxis, b0 as SeriesSpec, al as Fill, J as Background, aS as PriceLine, a8 as DrawingLine, a4 as DrawingBox, a7 as DrawingLabel, ac as DrawingPolyline, a9 as DrawingLinefill, ah as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, B as DrawingTypeKey, z as SnapMode, aa as DrawingMode, v as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, p as LegendActionView, q as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, s as ClickEvent, A as AxisLongPressEvent, w as DataWindowReadout, o as SymbolPickerFn, W as WallClock, bi as PaneInfo, ak as DrawingsOption, ae as DrawingSeriesGateway, bj as DrawingToolDefaults, bk as DrawingToolTemplate, D as Drawing, t as TimelineMark, u as MarkGroup, b as VelaOptions, G as AddIndicatorOptions, aI as MarketSwitch, F as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-B7aL1pbf.js';
+import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-CPFgSyAm.js';
+import { M as MessageLike, T as Translator, c as LocaleChangedEvent, b as LocalizationOptions } from './types-Bwf63xGI.js';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -553,14 +554,15 @@ interface NativeIndicator {
  */
 interface NativeIndicatorDescriptor {
     readonly type: string;
-    /** Full display name (picker, settings header, handle title). */
-    readonly title: string;
+    /** Full display name (picker, settings header, handle title). A message (`msg()`)
+     *  reads in the chart's language. */
+    readonly title: MessageLike;
     /**
      * Compact name for the on-chart legend chip, the settings-dialog header and the
      * object tree's indicator rows.
      * Absent ⇒ {@link title}. The picker keeps the full title either way.
      */
-    readonly shortTitle?: string;
+    readonly shortTitle?: MessageLike;
     readonly paneHint: 'price' | 'new';
     readonly overlay: boolean;
     /** Whether instances react to viewport changes (drives the orchestrator's viewport poke). */
@@ -628,12 +630,19 @@ interface NativeIndicatorInfo {
 declare function registerNativeIndicator(descriptor: NativeIndicatorDescriptor): void;
 /** Remove a registered native-indicator type (mainly for tests). */
 declare function unregisterNativeIndicator(type: string): void;
-/** Look up a registered native-indicator descriptor (undefined if the type isn't registered). */
-declare function getNativeIndicator(type: string): NativeIndicatorDescriptor | undefined;
+/** A registered descriptor as the read APIs hand it out: its names as plain text. */
+type ResolvedNativeIndicatorDescriptor = NativeIndicatorDescriptor & {
+    readonly title: string;
+    readonly shortTitle?: string;
+};
+/** Look up a registered native-indicator descriptor (undefined if the type isn't registered).
+ *  Its names read in `i18n`'s language (English without one). */
+declare function getNativeIndicator(type: string, i18n?: Translator): ResolvedNativeIndicatorDescriptor | undefined;
 /** All registered native-indicator types (for a host "add native indicator" menu). */
 declare function nativeIndicatorTypes(): string[];
-/** All registered native-indicator descriptors (for building a catalog with metadata + capability). */
-declare function nativeIndicatorDescriptors(): NativeIndicatorDescriptor[];
+/** All registered native-indicator descriptors (for building a catalog with metadata +
+ *  capability), their names in `i18n`'s language (English without one). */
+declare function nativeIndicatorDescriptors(i18n?: Translator): ResolvedNativeIndicatorDescriptor[];
 
 /**
  * Why a script computed. The distinction that matters most is `'tick'` vs `'bar'`: a tick
@@ -926,6 +935,12 @@ interface VelaEventMap extends Record<string, unknown> {
      * leave the app theme alone.
      */
     "theme:changed": VelaTheme;
+    /**
+     * The chart's localization changed through `chart.setLocale(...)` — after the chart has
+     * re-rendered its text and numbers. Carries the resolved locale and chrome direction so
+     * host chrome around the chart can follow.
+     */
+    "locale:changed": LocaleChangedEvent;
     /**
      * The base price style is switching `from` → `to` (candles, line, area, a chart-type
      * id, …). Fires synchronously BEFORE the chart repaints in the new style, whatever
@@ -1285,7 +1300,7 @@ declare class RendererControl {
     /** Contribute host settings tabs (callback rows) to the renderer's settings dialog —
      *  e.g. the widget's Status line toggles. Silent no-op without a dialog. */
     setSettingsSections(sections: ReadonlyArray<{
-        title: string;
+        title: MessageLike;
         rows: readonly unknown[];
         id?: string;
     }>): this;
@@ -1402,10 +1417,14 @@ interface AddInit {
  */
 declare class DrawingController {
     private readonly events;
+    /** The chart's translator: the toolbar reaches the renderer labelled in its language. */
+    private readonly i18n;
     private readonly store;
     private readonly history;
     private readonly port;
     private readonly enabled;
+    /** The toolbar as last configured — re-read in the chart's language on {@link relocalize}. */
+    private toolbarOption;
     private activeTool;
     /** Mirror of the renderer's sticky magnet mode (the renderer default is 'off'). */
     private snapMode;
@@ -1422,7 +1441,9 @@ declare class DrawingController {
     /** Per-tool saved looks ("styles"), in the order they were saved. */
     private templates;
     private readonly subs;
-    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>, option: DrawingsOption | undefined, seriesGateway?: DrawingSeriesGateway);
+    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>, option: DrawingsOption | undefined, seriesGateway?: DrawingSeriesGateway, 
+    /** The chart's translator: the toolbar reaches the renderer labelled in its language. */
+    i18n?: () => Translator | null);
     /** Whether the active renderer supports interactive drawings. */
     get supported(): boolean;
     setTool(type: DrawingTypeKey | null): void;
@@ -1461,6 +1482,8 @@ declare class DrawingController {
     removeToolTemplate(type: DrawingTypeKey, name: string): void;
     private pushTemplates;
     setToolbar(option: DrawingsOption): void;
+    /** The chart's language changed: hand the renderer the toolbar relabelled in it. */
+    relocalize(): void;
     /** Display (or clear) another chart's in-progress placement as a ghost — silently
      *  inert on a renderer without the optional `setExternalGhost` seam. */
     setExternalGhost(doc: SerializedDrawing | null): void;
@@ -1764,7 +1787,27 @@ declare class Vela {
     private readonly drawingsControl;
     private readonly marksControl;
     private readonly replayControl;
+    private readonly localeState;
+    private readonly rendererPort;
     constructor(container: HTMLElement | string, options?: VelaOptions, deps?: VelaDeps);
+    /**
+     * The chart's translator: its resolved locale and direction, `t()` for messages, and
+     * `format` for numbers and dates in the chart's locale. The same object for the
+     * chart's lifetime; it reads the new settings after {@link setLocale}.
+     */
+    get i18n(): Translator;
+    /**
+     * Change the chart's language, direction or formatting at runtime — a locale tag
+     * (`chart.setLocale('de')`) or any {@link LocalizationOptions} fields. Fields you pass
+     * replace their current value (an explicit `undefined` restores the default); the
+     * others are kept. The chart re-renders its text, axes and readouts in place (no
+     * indicator re-run) and emits `locale:changed`. Register the locale's pack
+     * (`registerLocale`) first for translated text.
+     */
+    setLocale(next: string | LocalizationOptions): this;
+    /** Hand the renderer the translator and the root attributes the host asked for: `lang`
+     *  once a locale is set, `dir` once a direction is (unset, the host page decides). */
+    private pushLocalization;
     /**
      * Register a scripting engine so `addIndicator({ language })` can run that
      * language. Vela ships NO engine — install the one you need (Pine Script:
@@ -1969,6 +2012,10 @@ interface WidgetContext {
      *  (Dialog/Menu/Tooltip) from an action; without an explicit host they portal to
      *  the body, OUTSIDE the theme variables. A multi-chart shell hands its own root. */
     host: HTMLElement;
+    /** The shell's translator: `i18n.t(msg(...))` for text an action or panel renders,
+     *  `i18n.format` for its numbers and dates, `i18n.direction` for its layout. It follows
+     *  `setLocale`; listen to the shell's `locale:changed` to re-render. */
+    i18n: Translator;
     /** The widget's feedback pill (bottom-center, auto-hides). */
     toast(message: string, kind?: 'info' | 'success' | 'error'): void;
     /** Add a SCRIPT indicator to the active chart THROUGH THE SHELL — unlike the raw
@@ -2037,8 +2084,9 @@ interface WidgetActionDescriptor {
     id: string;
     target: WidgetActionTarget;
     /** Always required, even icon-only: it is the button's aria-label and tooltip, the
-     *  mobile drawer row's text, and the context-menu item's label. */
-    label: string;
+     *  mobile drawer row's text, and the context-menu item's label. A message
+     *  (`msg(id, 'English')`) follows the shell's language; a plain string shows as is. */
+    label: MessageLike;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon?: string;
     /** Topbar only: render the DESKTOP button icon-only, like the built-in tools — the
@@ -2104,7 +2152,7 @@ interface SidePanelHeader {
     slot: HTMLElement;
     /** Replace the header title (an empty string hides it). The topbar toggle keeps the
      *  DECLARED `title` as its tooltip. */
-    setTitle(title: string): void;
+    setTitle(title: MessageLike): void;
     /** Whether the panel covers every chart right now (see `maximizable`). */
     readonly maximized: boolean;
     /** Maximize the panel over the shell's charts, or restore it — what its header button
@@ -2124,8 +2172,8 @@ interface SidePanelHeader {
 interface SidePanelDescriptor {
     /** Stable id — re-registering an id replaces it. Also the key its width persists under. */
     id: string;
-    /** Header title, and the tooltip of its topbar button. */
-    title: string;
+    /** Header title, and the tooltip of its topbar button. A message follows the shell's language. */
+    title: MessageLike;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon: string;
     /** Sort key among the panel buttons (ascending; default 100 — after the built-ins). */
@@ -2208,7 +2256,8 @@ interface LegendActionDescriptor {
     id: string;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon: string;
-    tooltip: string;
+    /** Hover text. A message follows the chart's language. */
+    tooltip: MessageLike;
     /** Sort key within the contributed group (ascending; default 0). */
     order?: number;
     /** Per-indicator gate — omitted ⇒ shown on every row. */
@@ -2225,10 +2274,10 @@ declare function legendActions(): LegendActionDescriptor[];
  *  indicator — the same signature as a legend action's `run`. */
 type LegendCalloutItem = {
     type: 'text';
-    text: string;
+    text: MessageLike;
 } | {
     type: 'button';
-    label: string;
+    label: MessageLike;
     /** Emphasized (selection-colored) button — the panel's main action. */
     primary?: boolean;
     /** Close the panel after `run` (default true). */
@@ -2237,7 +2286,7 @@ type LegendCalloutItem = {
 };
 /** The panel a clickable callout deploys: an optional heading over ordered blocks. */
 interface LegendCalloutContent {
-    title?: string;
+    title?: MessageLike;
     items: LegendCalloutItem[];
 }
 /** A callout's resolved presentation for one row — what {@link LegendCalloutDescriptor.callout} returns. */
@@ -2248,8 +2297,8 @@ interface LegendCalloutSpec {
     background: string;
     /** Icon ink (default: the legend row's text color). */
     color?: string;
-    /** Hover text; also the bubble's accessible name. */
-    tooltip: string;
+    /** Hover text; also the bubble's accessible name. A message follows the chart's language. */
+    tooltip: MessageLike;
     /** Deployed panel — presence makes the bubble clickable. */
     content?: LegendCalloutContent;
 }

package/dist/{contributions-P9fBBuY1.d.ts → contributions-DupwEkzc.d.cts}

@@ -1,5 +1,6 @@
-import { x as Millis, ao as InputSchema, am as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, l as IndicatorModel, k as MoveTarget, aH as PaneAxis, a_ as SeriesSpec, ak as Fill, H as Background, aQ as PriceLine, a7 as DrawingLine, a3 as DrawingBox, a6 as DrawingLabel, ab as DrawingPolyline, a8 as DrawingLinefill, ag as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, z as DrawingTypeKey, y as SnapMode, a9 as DrawingMode, u as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, o as LegendActionView, p as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, r as ClickEvent, A as AxisLongPressEvent, v as DataWindowReadout, n as SymbolPickerFn, W as WallClock, bg as PaneInfo, aj as DrawingsOption, ad as DrawingSeriesGateway, bh as DrawingToolDefaults, bi as DrawingToolTemplate, D as Drawing, s as TimelineMark, t as MarkGroup, b as VelaOptions, F as AddIndicatorOptions, aG as MarketSwitch, E as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-BI5Tp32b.js';
-import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-BUdlkx9I.js';
+import { y as Millis, aq as InputSchema, an as IndicatorMeta, P as PriceStyle, O as OHLCV, I as InputValue, m as IndicatorModel, l as MoveTarget, aJ as PaneAxis, b0 as SeriesSpec, al as Fill, J as Background, aS as PriceLine, a8 as DrawingLine, a4 as DrawingBox, a7 as DrawingLabel, ac as DrawingPolyline, a9 as DrawingLinefill, ah as DrawingTable, h as IndicatorStatus, a as VisibleRange, c as VelaTheme, S as SerializedDrawing, B as DrawingTypeKey, z as SnapMode, aa as DrawingMode, v as MarkClickEvent, e as IChartRenderer, R as RendererCapabilities, p as LegendActionView, q as LegendCalloutView, U as Unsubscribe, C as CrosshairEvent, s as ClickEvent, A as AxisLongPressEvent, w as DataWindowReadout, o as SymbolPickerFn, W as WallClock, bi as PaneInfo, ak as DrawingsOption, ae as DrawingSeriesGateway, bj as DrawingToolDefaults, bk as DrawingToolTemplate, D as Drawing, t as TimelineMark, u as MarkGroup, b as VelaOptions, G as AddIndicatorOptions, aI as MarketSwitch, F as MarketSnapshot, V as VisibleRangePreset, T as ThemeName } from './options-I1H2HDWw.cjs';
+import { S as SymbolInfo, B as BarRange, M as MarketDataFeed, D as DataProvider, P as ProviderInfo, a as SymbolDescriptor, b as ProviderCapabilities } from './DataProvider-B5i0_yY4.cjs';
+import { M as MessageLike, T as Translator, c as LocaleChangedEvent, b as LocalizationOptions } from './types-Bwf63xGI.cjs';
 
 /**
  * A strategy's broker state at ONE bar — the flat summary a host reads while a script
@@ -553,14 +554,15 @@ interface NativeIndicator {
  */
 interface NativeIndicatorDescriptor {
     readonly type: string;
-    /** Full display name (picker, settings header, handle title). */
-    readonly title: string;
+    /** Full display name (picker, settings header, handle title). A message (`msg()`)
+     *  reads in the chart's language. */
+    readonly title: MessageLike;
     /**
      * Compact name for the on-chart legend chip, the settings-dialog header and the
      * object tree's indicator rows.
      * Absent ⇒ {@link title}. The picker keeps the full title either way.
      */
-    readonly shortTitle?: string;
+    readonly shortTitle?: MessageLike;
     readonly paneHint: 'price' | 'new';
     readonly overlay: boolean;
     /** Whether instances react to viewport changes (drives the orchestrator's viewport poke). */
@@ -628,12 +630,19 @@ interface NativeIndicatorInfo {
 declare function registerNativeIndicator(descriptor: NativeIndicatorDescriptor): void;
 /** Remove a registered native-indicator type (mainly for tests). */
 declare function unregisterNativeIndicator(type: string): void;
-/** Look up a registered native-indicator descriptor (undefined if the type isn't registered). */
-declare function getNativeIndicator(type: string): NativeIndicatorDescriptor | undefined;
+/** A registered descriptor as the read APIs hand it out: its names as plain text. */
+type ResolvedNativeIndicatorDescriptor = NativeIndicatorDescriptor & {
+    readonly title: string;
+    readonly shortTitle?: string;
+};
+/** Look up a registered native-indicator descriptor (undefined if the type isn't registered).
+ *  Its names read in `i18n`'s language (English without one). */
+declare function getNativeIndicator(type: string, i18n?: Translator): ResolvedNativeIndicatorDescriptor | undefined;
 /** All registered native-indicator types (for a host "add native indicator" menu). */
 declare function nativeIndicatorTypes(): string[];
-/** All registered native-indicator descriptors (for building a catalog with metadata + capability). */
-declare function nativeIndicatorDescriptors(): NativeIndicatorDescriptor[];
+/** All registered native-indicator descriptors (for building a catalog with metadata +
+ *  capability), their names in `i18n`'s language (English without one). */
+declare function nativeIndicatorDescriptors(i18n?: Translator): ResolvedNativeIndicatorDescriptor[];
 
 /**
  * Why a script computed. The distinction that matters most is `'tick'` vs `'bar'`: a tick
@@ -926,6 +935,12 @@ interface VelaEventMap extends Record<string, unknown> {
      * leave the app theme alone.
      */
     "theme:changed": VelaTheme;
+    /**
+     * The chart's localization changed through `chart.setLocale(...)` — after the chart has
+     * re-rendered its text and numbers. Carries the resolved locale and chrome direction so
+     * host chrome around the chart can follow.
+     */
+    "locale:changed": LocaleChangedEvent;
     /**
      * The base price style is switching `from` → `to` (candles, line, area, a chart-type
      * id, …). Fires synchronously BEFORE the chart repaints in the new style, whatever
@@ -1285,7 +1300,7 @@ declare class RendererControl {
     /** Contribute host settings tabs (callback rows) to the renderer's settings dialog —
      *  e.g. the widget's Status line toggles. Silent no-op without a dialog. */
     setSettingsSections(sections: ReadonlyArray<{
-        title: string;
+        title: MessageLike;
         rows: readonly unknown[];
         id?: string;
     }>): this;
@@ -1402,10 +1417,14 @@ interface AddInit {
  */
 declare class DrawingController {
     private readonly events;
+    /** The chart's translator: the toolbar reaches the renderer labelled in its language. */
+    private readonly i18n;
     private readonly store;
     private readonly history;
     private readonly port;
     private readonly enabled;
+    /** The toolbar as last configured — re-read in the chart's language on {@link relocalize}. */
+    private toolbarOption;
     private activeTool;
     /** Mirror of the renderer's sticky magnet mode (the renderer default is 'off'). */
     private snapMode;
@@ -1422,7 +1441,9 @@ declare class DrawingController {
     /** Per-tool saved looks ("styles"), in the order they were saved. */
     private templates;
     private readonly subs;
-    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>, option: DrawingsOption | undefined, seriesGateway?: DrawingSeriesGateway);
+    constructor(renderer: IChartRenderer, events: TypedEventBus<VelaEventMap>, option: DrawingsOption | undefined, seriesGateway?: DrawingSeriesGateway, 
+    /** The chart's translator: the toolbar reaches the renderer labelled in its language. */
+    i18n?: () => Translator | null);
     /** Whether the active renderer supports interactive drawings. */
     get supported(): boolean;
     setTool(type: DrawingTypeKey | null): void;
@@ -1461,6 +1482,8 @@ declare class DrawingController {
     removeToolTemplate(type: DrawingTypeKey, name: string): void;
     private pushTemplates;
     setToolbar(option: DrawingsOption): void;
+    /** The chart's language changed: hand the renderer the toolbar relabelled in it. */
+    relocalize(): void;
     /** Display (or clear) another chart's in-progress placement as a ghost — silently
      *  inert on a renderer without the optional `setExternalGhost` seam. */
     setExternalGhost(doc: SerializedDrawing | null): void;
@@ -1764,7 +1787,27 @@ declare class Vela {
     private readonly drawingsControl;
     private readonly marksControl;
     private readonly replayControl;
+    private readonly localeState;
+    private readonly rendererPort;
     constructor(container: HTMLElement | string, options?: VelaOptions, deps?: VelaDeps);
+    /**
+     * The chart's translator: its resolved locale and direction, `t()` for messages, and
+     * `format` for numbers and dates in the chart's locale. The same object for the
+     * chart's lifetime; it reads the new settings after {@link setLocale}.
+     */
+    get i18n(): Translator;
+    /**
+     * Change the chart's language, direction or formatting at runtime — a locale tag
+     * (`chart.setLocale('de')`) or any {@link LocalizationOptions} fields. Fields you pass
+     * replace their current value (an explicit `undefined` restores the default); the
+     * others are kept. The chart re-renders its text, axes and readouts in place (no
+     * indicator re-run) and emits `locale:changed`. Register the locale's pack
+     * (`registerLocale`) first for translated text.
+     */
+    setLocale(next: string | LocalizationOptions): this;
+    /** Hand the renderer the translator and the root attributes the host asked for: `lang`
+     *  once a locale is set, `dir` once a direction is (unset, the host page decides). */
+    private pushLocalization;
     /**
      * Register a scripting engine so `addIndicator({ language })` can run that
      * language. Vela ships NO engine — install the one you need (Pine Script:
@@ -1969,6 +2012,10 @@ interface WidgetContext {
      *  (Dialog/Menu/Tooltip) from an action; without an explicit host they portal to
      *  the body, OUTSIDE the theme variables. A multi-chart shell hands its own root. */
     host: HTMLElement;
+    /** The shell's translator: `i18n.t(msg(...))` for text an action or panel renders,
+     *  `i18n.format` for its numbers and dates, `i18n.direction` for its layout. It follows
+     *  `setLocale`; listen to the shell's `locale:changed` to re-render. */
+    i18n: Translator;
     /** The widget's feedback pill (bottom-center, auto-hides). */
     toast(message: string, kind?: 'info' | 'success' | 'error'): void;
     /** Add a SCRIPT indicator to the active chart THROUGH THE SHELL — unlike the raw
@@ -2037,8 +2084,9 @@ interface WidgetActionDescriptor {
     id: string;
     target: WidgetActionTarget;
     /** Always required, even icon-only: it is the button's aria-label and tooltip, the
-     *  mobile drawer row's text, and the context-menu item's label. */
-    label: string;
+     *  mobile drawer row's text, and the context-menu item's label. A message
+     *  (`msg(id, 'English')`) follows the shell's language; a plain string shows as is. */
+    label: MessageLike;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon?: string;
     /** Topbar only: render the DESKTOP button icon-only, like the built-in tools — the
@@ -2104,7 +2152,7 @@ interface SidePanelHeader {
     slot: HTMLElement;
     /** Replace the header title (an empty string hides it). The topbar toggle keeps the
      *  DECLARED `title` as its tooltip. */
-    setTitle(title: string): void;
+    setTitle(title: MessageLike): void;
     /** Whether the panel covers every chart right now (see `maximizable`). */
     readonly maximized: boolean;
     /** Maximize the panel over the shell's charts, or restore it — what its header button
@@ -2124,8 +2172,8 @@ interface SidePanelHeader {
 interface SidePanelDescriptor {
     /** Stable id — re-registering an id replaces it. Also the key its width persists under. */
     id: string;
-    /** Header title, and the tooltip of its topbar button. */
-    title: string;
+    /** Header title, and the tooltip of its topbar button. A message follows the shell's language. */
+    title: MessageLike;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon: string;
     /** Sort key among the panel buttons (ascending; default 100 — after the built-ins). */
@@ -2208,7 +2256,8 @@ interface LegendActionDescriptor {
     id: string;
     /** Icon id from the `vela/ui` icon registry (register yours with `registerIcon`). */
     icon: string;
-    tooltip: string;
+    /** Hover text. A message follows the chart's language. */
+    tooltip: MessageLike;
     /** Sort key within the contributed group (ascending; default 0). */
     order?: number;
     /** Per-indicator gate — omitted ⇒ shown on every row. */
@@ -2225,10 +2274,10 @@ declare function legendActions(): LegendActionDescriptor[];
  *  indicator — the same signature as a legend action's `run`. */
 type LegendCalloutItem = {
     type: 'text';
-    text: string;
+    text: MessageLike;
 } | {
     type: 'button';
-    label: string;
+    label: MessageLike;
     /** Emphasized (selection-colored) button — the panel's main action. */
     primary?: boolean;
     /** Close the panel after `run` (default true). */
@@ -2237,7 +2286,7 @@ type LegendCalloutItem = {
 };
 /** The panel a clickable callout deploys: an optional heading over ordered blocks. */
 interface LegendCalloutContent {
-    title?: string;
+    title?: MessageLike;
     items: LegendCalloutItem[];
 }
 /** A callout's resolved presentation for one row — what {@link LegendCalloutDescriptor.callout} returns. */
@@ -2248,8 +2297,8 @@ interface LegendCalloutSpec {
     background: string;
     /** Icon ink (default: the legend row's text color). */
     color?: string;
-    /** Hover text; also the bubble's accessible name. */
-    tooltip: string;
+    /** Hover text; also the bubble's accessible name. A message follows the chart's language. */
+    tooltip: MessageLike;
     /** Deployed panel — presence makes the bubble clickable. */
     content?: LegendCalloutContent;
 }