@squadbase/vantage 0.6.2-dev1.9365dcd → 0.6.2-dev1.9d7130b

package/registry/ui/waterfall-chart.tsx

@@ -32,7 +32,8 @@ import { EChart } from "@squadbase/vantage/components"
 import type { Polarity } from "@squadbase/vantage/components"
 import { EMPTY_VALUE, MINUS_SIGN } from "@squadbase/vantage/components"
 import type { ChartCommonProps, NumericKeys, ValueFormatter } from "@squadbase/vantage/components"
-import { createContext, useCallback, useEffect, useRef, useState } from "react"
+import { useSyncExternalStore } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, type RefObject } from "react"
 import type { ChartTone } from "@squadbase/vantage/components"
 import { type ReactNode } from "react"
 import { computeComparison, defaultChangeDisplay, formatChange, toneForValue, type ComparisonKind, type PeriodGrain } from "@squadbase/vantage/components"
@@ -41,6 +42,137 @@ import type { ChartThreshold, ChartAnnotation, ChartEventPayload, ChartForecast,
 import { formatValue, toValueFormatter } from "@squadbase/vantage/components"
 import type { ChartColor, ChartColors, ChartSeriesColor } from "@squadbase/vantage/components"
 
+/* ---------- inlined from @squadbase/squadkit registry/lib/locale.ts (internal to @squadbase/vantage) ---------- */
+
+/**
+ * The display language of the parts and the defaults that follow it.
+ *
+ * The language comes from `<html lang>`: a tag starting with `ja` reads Japanese, anything else English.
+ * Without a usable `lang` (missing, invalid, or no `document` — SSR, Node) the locale is `FALLBACK_LOCALE`
+ * (`en-US`). A `locale` passed explicitly (a prop, an argument) always wins.
+ *
+ * Parts read the locale through `useLocale` (`hooks/use-locale`) and pass it down; the pure helpers here
+ * and in `format` / `comparison` / `chart-*` take it as an argument and fall back to `documentLocale()`.
+ */
+
+/** The language of the built-in wording: Japanese or English. */
+type UiLanguage = "ja" | "en"
+
+/** The locale used when `<html lang>` gives none (and on the server). */
+const FALLBACK_LOCALE = "en-US"
+
+/** `"ja"` when `locale` starts with `ja` (`ja`, `ja-JP`), else `"en"`. A missing locale is `"en"`. */
+function uiLanguage(locale: string | null | undefined): UiLanguage {
+  return typeof locale === "string" && locale.trim().toLowerCase().startsWith("ja") ? "ja" : "en"
+}
+
+/** A BCP 47 tag in its canonical form (`en-gb` → `en-GB`), or `FALLBACK_LOCALE` when it is empty or invalid. */
+function normalizeLocale(tag: string | null | undefined): string {
+  const value = tag?.trim()
+  if (!value) return FALLBACK_LOCALE
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? FALLBACK_LOCALE
+  } catch {
+    return FALLBACK_LOCALE
+  }
+}
+
+/**
+ * The locale of the page: `document.documentElement.lang`, canonicalized. `FALLBACK_LOCALE` when it is empty or
+ * invalid, or there is no `document`. Parts read it through `useLocale`, never while rendering.
+ */
+function documentLocale(): string {
+  if (typeof document === "undefined") return FALLBACK_LOCALE
+  return normalizeLocale(document.documentElement?.getAttribute("lang"))
+}
+
+/** `locale` when given, else the page's locale (`documentLocale()`). */
+function resolveLocale(locale?: string | null): string {
+  return locale || documentLocale()
+}
+
+/** Picks the wording table of the locale's language. */
+function pickLocale<T>(table: { ja: T; en: T }, locale?: string | null): T {
+  return table[uiLanguage(resolveLocale(locale))]
+}
+
+/** The currency `format="currency"` uses without a `currency`: JPY for Japanese, USD otherwise. */
+function defaultCurrency(locale?: string | null): string {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? "JPY" : "USD"
+}
+
+/** The month a fiscal year starts in (1–12) when none is given: April for Japanese, January otherwise. */
+function defaultFiscalYearStartMonth(locale?: string | null): number {
+  return uiLanguage(resolveLocale(locale)) === "ja" ? 4 : 1
+}
+
+/** A day of the week, 0 = Sunday … 6 = Saturday (the `Date#getDay` / date-fns numbering). */
+type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+/** Locales whose week starts on Sunday when the runtime has no week data. */
+const SUNDAY_FIRST = new Set(["en", "en-US", "en-CA"])
+
+/**
+ * The first day of the week: Monday for Japanese; otherwise the locale's convention from `Intl.Locale`
+ * (`en-US` Sunday, `en-GB` Monday). Without week data in the runtime: Sunday for `en` / `en-US` / `en-CA`,
+ * Monday for the rest.
+ */
+function weekStartsOn(locale?: string | null): WeekDay {
+  const tag = normalizeLocale(resolveLocale(locale))
+  if (uiLanguage(tag) === "ja") return 1
+  try {
+    const info = new Intl.Locale(tag) as Intl.Locale & {
+      getWeekInfo?: () => { firstDay: number }
+      weekInfo?: { firstDay: number }
+    }
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay
+    if (typeof firstDay === "number" && firstDay >= 1 && firstDay <= 7) return (firstDay % 7) as WeekDay
+  } catch {
+    // Fall through to the table below.
+  }
+  return SUNDAY_FIRST.has(tag) ? 0 : 1
+}
+
+/* ---------- inlined from @squadbase/squadkit registry/hooks/use-locale.ts (internal to @squadbase/vantage) ---------- */
+
+const listeners = new Set<() => void>()
+let observer: MutationObserver | null = null
+
+/** One observer on `<html lang>` for every subscribed part. */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {}
+  listeners.add(onChange)
+  if (!observer) {
+    observer = new MutationObserver(() => {
+      for (const listener of [...listeners]) listener()
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] })
+  }
+  return () => {
+    listeners.delete(onChange)
+    if (listeners.size === 0 && observer) {
+      observer.disconnect()
+      observer = null
+    }
+  }
+}
+
+const serverLocale = () => FALLBACK_LOCALE
+
+/**
+ * The page's locale (`<html lang>`), following changes made while the page runs. On the server and during
+ * hydration it is `FALLBACK_LOCALE` (`en-US`), so the markup matches; it switches right after.
+ */
+function useDocumentLocale(): string {
+  return useSyncExternalStore(subscribe, documentLocale, serverLocale)
+}
+
+/** The locale a part renders in: its `locale` prop when given, else the page's (`useDocumentLocale`). */
+function useLocale(locale?: string | null): string {
+  const page = useDocumentLocale()
+  return locale || page
+}
+
 /* ---------- inlined from @squadbase/squadkit registry/lib/chart-theme.ts (internal to @squadbase/vantage) ---------- */
 
 /**
@@ -75,10 +207,23 @@ interface ChartTokens {
   border: string | null
   /** Tooltip surface. */
   popover: string | null
+  /** Semantic and surface dependencies used by typed chart options. Optional for hand-built tokens. */
+  colors?: Record<string, string>
+  /** Actual inherited painting surface (may change without a token changing). */
+  surface?: string | null
   /** Tooltip text. */
   popoverForeground: string | null
 }
 
+// Keep scope out of the public token shape. A resolved snapshot remembers where arbitrary
+// var(--token) expressions must be read, without retaining unmounted charts globally.
+const tokenScopes = new WeakMap<ChartTokens, Element>()
+const OPTION_COLOR_TOKENS = [
+  "--background", "--card", "--muted", "--primary", "--destructive",
+  ...["positive", "negative", "warning", "neutral", "info"].flatMap((tone) =>
+    ["", "-fill", "-subtle"].map((suffix) => `--${tone}${suffix}`)),
+]
+
 let normalizeContext: CanvasRenderingContext2D | null | undefined
 
 /** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
@@ -134,8 +279,10 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     const color = read(token)
     if (color) series.push(color)
   }
-  return {
+  const tokens: ChartTokens = {
     series,
+    colors: Object.fromEntries(OPTION_COLOR_TOKENS.map((name) => [name, styles.getPropertyValue(name).trim()])),
+    surface: readChartSurface(target),
     ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
     foreground: read("--foreground"),
     mutedForeground: read("--muted-foreground"),
@@ -143,6 +290,8 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     popover: read("--popover"),
     popoverForeground: read("--popover-foreground"),
   }
+  tokenScopes.set(tokens, target)
+  return tokens
 }
 
 /** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
@@ -150,6 +299,10 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
   if (a === b) return true
   if (!a || !b) return false
   return (
+    tokenScopes.get(a) === tokenScopes.get(b) &&
+    a.surface === b.surface &&
+    Object.keys(a.colors ?? {}).length === Object.keys(b.colors ?? {}).length &&
+    Object.entries(a.colors ?? {}).every(([name, value]) => b.colors?.[name] === value) &&
     a.series.length === b.series.length &&
     a.series.every((color, i) => color === b.series[i]) &&
     a.fontFamily === b.fontFamily &&
@@ -175,7 +328,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
  *    attributes alone leaves the chart painted in the previous palette until a
  *    reload — the tokens in the DOM are new, the canvas is not.
  */
-function watchChartTokens(onChange: () => void): () => void {
+function watchChartTokens(onChange: () => void, scope?: Element | null): () => void {
   if (typeof document === "undefined") return () => {}
   // Style edits arrive as bursts of mutations; coalesce them into one read, and
   // take it after the next frame so a swapped stylesheet has been applied.
@@ -190,8 +343,11 @@ function watchChartTokens(onChange: () => void): () => void {
 
   const themeObserver = new MutationObserver(schedule)
   const attributeFilter = ["class", "style", "data-theme"]
-  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
-  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+  // Only the chart and its ancestors can change its inherited theme. Never observe
+  // the document subtree: canvas/tooltip/rendering mutations would trigger every chart.
+  for (let node: Element | null = scope ?? document.body ?? document.documentElement; node; node = node.parentElement) {
+    themeObserver.observe(node, { attributes: true, attributeFilter })
+  }
 
   const styleObserver = new MutationObserver(schedule)
   if (document.head) {
@@ -279,22 +435,23 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  * components that build an ECharts option from token colours themselves (the
  * typed charts), so their palette follows light/dark like `EChart`'s theme.
  */
-function useChartTokens(): ChartTokens | null {
+function useChartTokens(scope?: Element | null | RefObject<Element | null>): ChartTokens | null {
   const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
   // Compared here, not inside a `setTokens` updater: an updater that reads the DOM is
   // replayed by React on every rebase and returns a fresh object each time, so the state
   // never settles ("Maximum update depth exceeded" once the tokens change after mount).
   const tokensRef = useRef(tokens)
   useEffect(() => {
+    const target = scope && "current" in scope ? scope.current : scope
     const sync = () => {
-      const next = readChartTokens()
+      const next = readChartTokens(target)
       if (sameChartTokens(tokensRef.current, next)) return
       tokensRef.current = next
       setTokens(next)
     }
     sync()
-    return watchChartTokens(sync)
-  }, [])
+    return watchChartTokens(sync, target)
+  }, [scope])
   return tokens
 }
 
@@ -306,7 +463,7 @@ const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
 /**
  * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
  * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
- * variants `"positive-fill"`, …) are read off the document root (`--positive`, …); `var(--token)` is read off the document root; any
+ * variants `"positive-fill"`, …) are read in the snapshot's inherited scope (`--positive`, …); `var(--token)` uses the same scope; any
  * other CSS colour is normalized like the tokens are. A colour that can't be
  * resolved comes back as `""`, which ECharts treats as "use the palette".
  */
@@ -317,12 +474,13 @@ function resolveChartColors(colors: readonly string[], tokens: ChartTokens | nul
     // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
     if (TONE_NAME_RE.test(color.trim())) {
       if (typeof document === "undefined") return ""
-      return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue(`--${color.trim()}`)) ?? ""
+      const target = (tokens && tokenScopes.get(tokens)) ?? document.documentElement
+      return toCanvasColor(getComputedStyle(target).getPropertyValue(`--${color.trim()}`)) ?? ""
     }
     if (typeof document === "undefined") return color
     let value = color.trim()
     const cssVar = CSS_VAR_RE.exec(value)
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle((tokens && tokenScopes.get(tokens)) ?? document.documentElement)
     if (cssVar) {
       value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
     } else if (value.includes("var(")) {
@@ -368,7 +526,7 @@ function readChartSurface(el: Element | null): string | null {
       if (color) return color
     }
   }
-  return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue("--background"))
+  return toCanvasColor(getComputedStyle(el ?? document.documentElement).getPropertyValue("--background"))
 }
 
 /** Widths are bucketed so a resize only rebuilds the option when the label budget can change. */
@@ -382,9 +540,10 @@ const WIDTH_BUCKET = 40
  */
 function useChartSurface<E extends Element>(
   forwarded: ForwardedRef<E>,
-  tokens: ChartTokens | null,
-): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined } {
+  tokens?: ChartTokens | null,
+): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined; tokens: ChartTokens | null } {
   const [node, setNode] = useState<E | null>(null)
+  const scopedTokens = useChartTokens(node)
   const [surface, setSurface] = useState<string | undefined>(undefined)
   const [width, setWidth] = useState<number | undefined>(undefined)
   const ref = useCallback(
@@ -398,7 +557,7 @@ function useChartSurface<E extends Element>(
   useEffect(() => {
     if (!node) return
     setSurface(readChartSurface(node) ?? undefined)
-  }, [node, tokens])
+  }, [node, tokens, scopedTokens])
   useEffect(() => {
     if (!node || typeof ResizeObserver === "undefined") return
     const update = (w: number) => setWidth(Math.floor(w / WIDTH_BUCKET) * WIDTH_BUCKET)
@@ -407,11 +566,37 @@ function useChartSurface<E extends Element>(
     observer.observe(node)
     return () => observer.disconnect()
   }, [node])
-  return { ref, surface, width }
+  return { ref, surface, width, tokens: scopedTokens }
 }
 
 /* ---------- inlined from @squadbase/squadkit registry/lib/chart-options.ts (internal to @squadbase/vantage) ---------- */
 
+/** The built-in words of the option builders, by language. */
+const CHART_TEXT = {
+  ja: {
+    target: "目標",
+    forecast: "予測",
+    total: "合計",
+    provisional: "速報",
+    noComparison: "比較なし",
+    share: (share: string) => `（${share}）`,
+    targetRate: (rate: string) => `（達成率 ${rate}）`,
+    provisionalTitle: (title: string, label: string) => `${title}(${label})`,
+  },
+  en: {
+    target: "Target",
+    forecast: "Forecast",
+    total: "Total",
+    provisional: "Preliminary",
+    noComparison: "No comparison",
+    share: (share: string) => ` (${share})`,
+    targetRate: (rate: string) => ` (${rate} achieved)`,
+    provisionalTitle: (title: string, label: string) => `${title} (${label})`,
+  },
+} satisfies Record<UiLanguage, unknown>
+
+const chartText = (locale?: string) => CHART_TEXT[uiLanguage(resolveLocale(locale))]
+
 type CartesianChartKind = "area" | "bar" | "line"
 type CartesianStackType = "default" | "stacked" | "percent"
 type CartesianCurveType = "linear" | "smooth" | "step"
@@ -596,7 +781,7 @@ interface CartesianChartConfig {
    * all ticks read in one unit (¥0.5億 / ¥1億). Default: `axisFormatter` for every tick.
    */
   axisTicks?: (top: number) => (value: number) => string
-  /** Locale of the time-axis labels. Default `"ja-JP"`. */
+  /** Locale of the time-axis labels and the built-in words (total, target, forecast). Default the page's (`<html lang>`). */
   locale?: string
   type?: CartesianStackType
   /** Bar only. `"vertical"` lays the categories down the y axis (horizontal bars). */
@@ -834,11 +1019,12 @@ function timeAxisLabelStep(values: readonly unknown[], maxLabels: number = TIME_
  */
 function timeAxisLabels(
   values: readonly unknown[],
-  locale: string = DEFAULT_LOCALE,
+  localeArg?: string,
   shown: (i: number) => boolean = () => true,
 ): string[] | null {
   const parsed = parseTimeIndex(values)
   if (!parsed) return null
+  const locale = resolveLocale(localeArg)
   const { granularity, times } = parsed
   let prevYear: number | null = null
   return times.map((t, i) => {
@@ -861,9 +1047,10 @@ function timeAxisLabels(
 }
 
 /** The tooltip titles for time-like x values (`2025年9月`, `2025年9月1日`), or `null` when they are not dates. */
-function timeTooltipLabels(values: readonly unknown[], locale: string = DEFAULT_LOCALE): string[] | null {
+function timeTooltipLabels(values: readonly unknown[], localeArg?: string): string[] | null {
   const parsed = parseTimeIndex(values)
   if (!parsed) return null
+  const locale = resolveLocale(localeArg)
   const options: Intl.DateTimeFormatOptions =
     parsed.granularity === "year"
       ? { year: "numeric" }
@@ -1003,7 +1190,9 @@ function tooltipHtml(
   rows: readonly TooltipRow[],
   valueFormatter: (value: number) => string,
   notes: readonly string[] = [],
+  locale?: string,
 ): string {
+  const t = chartText(locale)
   const lines = rows.map(
     (row) =>
       `<div style="display:flex;align-items:center;gap:8px;line-height:20px">` +
@@ -1012,7 +1201,7 @@ function tooltipHtml(
       `<span style="font-weight:600;font-variant-numeric:tabular-nums;margin-left:12px">${
         row.value === null ? EMPTY_VALUE : escapeHtml(valueFormatter(row.value))
       }${
-        row.share === undefined ? "" : `<span style="opacity:.6;margin-left:4px">（${escapeHtml(formatShare(row.share))}）</span>`
+        row.share === undefined ? "" : `<span style="opacity:.6;margin-left:4px">${escapeHtml(t.share(formatShare(row.share)))}</span>`
       }</span></div>` +
       (row.note === undefined
         ? ""
@@ -1026,8 +1215,10 @@ function tooltipHtml(
 
 /* ------------------------------------------------- per-bar targets / notes */
 
-/** Default name of the per-bar target marker (legend, tooltip). */
-const BAR_TARGET_LABEL = "目標"
+/** Default name of the per-bar target marker (legend, tooltip) in `locale`: "Target" / 「目標」. Default the page's locale. */
+function barTargetLabel(locale?: string): string {
+  return chartText(locale).target
+}
 
 /** How far (px) the target marker reaches past each side of its bar. */
 const TARGET_MARKER_OVERHANG = 4
@@ -1078,16 +1269,17 @@ function achievementRate(value: number | null | undefined, target: number | null
   return (value / target) * 100
 }
 
-/** The tooltip line of a bar with a target: 「目標 ¥1,200万（達成率 85.3%）」. `null` without a target. */
+/** The tooltip line of a bar with a target: 「目標 ¥1,200万（達成率 85.3%）」 / "Target $12M (85.3% achieved)". `null` without a target. */
 function barTargetNote(
   label: string,
   value: number | null,
   target: number | null,
   valueFormatter: (value: number) => string,
+  locale?: string,
 ): string | null {
   if (target === null) return null
   const rate = achievementRate(value, target)
-  return `${label} ${valueFormatter(target)}${rate === null ? "" : `（達成率 ${formatShare(rate)}）`}`
+  return `${label} ${valueFormatter(target)}${rate === null ? "" : chartText(locale).targetRate(formatShare(rate))}`
 }
 
 /** Half the width of a bar in category-axis units, from `barCategoryGap` (`"20%"`; a px gap or none → ECharts' 20%). */
@@ -1179,11 +1371,12 @@ const TARGET_LEGEND_SERIES_ID = "__target-legend"
 /** A flat tick (8×8 legend box, aspect kept): the per-bar target's legend icon. */
 const TARGET_LEGEND_ICON = "path://M0,0 L100,0 L100,24 L0,24 Z"
 
-const DEFAULT_FORECAST_LABEL = "予測"
-
-/** The label at the top of a forecast's boundary line: the forecast's name (as in the legend) and an arrow toward the forecast side. */
-function forecastBoundaryText(label: string = DEFAULT_FORECAST_LABEL): string {
-  return `${label} →`
+/**
+ * The label at the top of a forecast's boundary line: the forecast's name (as in the legend) and an arrow toward the forecast side.
+ * Without a `label`, "Forecast" / 「予測」 in `locale` (default the page's).
+ */
+function forecastBoundaryText(label?: string, locale?: string): string {
+  return `${label ?? chartText(locale).forecast} →`
 }
 
 /** A comparison series: a thin, muted, solid line with no markers (60% of `--muted-foreground`). */
@@ -1223,8 +1416,10 @@ interface AxisExtent {
   max: number
 }
 
-/** The label of a stack's total (highlight and tooltip). */
-const STACK_TOTAL_LABEL = "合計"
+/** The label of a stack's total (highlight and tooltip) in `locale`: "Total" / 「合計」. Default the page's locale. */
+function stackTotalLabel(locale?: string): string {
+  return chartText(locale).total
+}
 
 /** Per point, the sum of the stacked series; `null` where every series is missing. */
 function stackTotalsOf(values: readonly (readonly (number | null)[])[]): (number | null)[] {
@@ -1346,8 +1541,8 @@ function indexGrain(values: readonly unknown[]): PeriodGrain | null {
 
 /**
  * The tooltip line under the main series' row when a comparison series is drawn: the arrow, the signed change and the
- * comparison's name, as `Delta` writes it ("↑ +12.4% 前年同月比"; a minus is U+2212). "比較なし 前年同月比" when
- * either value is missing or the baseline is 0.
+ * comparison's name, as `Delta` writes it ("↑ +12.4% vs. same month last year" / "↑ +12.4% 前年同月比"; a minus is U+2212).
+ * "No comparison vs. same month last year" / "比較なし 前年同月比" when either value is missing or the baseline is 0.
  */
 function comparisonNote(
   current: number | null,
@@ -1355,16 +1550,18 @@ function comparisonNote(
   comparison: Pick<CartesianComparisonConfig, "vs" | "label">,
   grain?: PeriodGrain,
   format?: ValueFormat,
-  locale: string = DEFAULT_LOCALE,
+  localeArg?: string,
 ): string {
+  const locale = resolveLocale(localeArg)
   const result = computeComparison(
     current,
     comparison.vs === "custom"
       ? { previous, vs: "custom", label: comparison.label ?? "", grain }
       : { previous, vs: comparison.vs, label: comparison.label, grain },
+    { locale },
   )
   const text = formatChange(result, defaultChangeDisplay(format), locale, format)
-  if (text === null) return `比較なし ${result.label}`
+  if (text === null) return `${chartText(locale).noComparison} ${result.label}`
   const arrow = result.direction === "up" ? "↑" : result.direction === "down" ? "↓" : "→"
   return `${arrow} ${text.replace(/^-/, "−")} ${result.label}`
 }
@@ -1407,7 +1604,6 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     toneColors,
     valueFormatter,
     axisFormatter = valueFormatter,
-    locale = DEFAULT_LOCALE,
     type = "default",
     layout = "horizontal",
     curveType = "linear",
@@ -1444,7 +1640,9 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     chartOptions,
     reserveActions = false,
   } = cfg
-  const provisionalLabel = cfg.provisionalLabel ?? DEFAULT_PROVISIONAL_LABEL
+  const locale = resolveLocale(cfg.locale)
+  const text = chartText(locale)
+  const provisionalLabel = cfg.provisionalLabel ?? text.provisional
 
   const stacked = kind !== "line" && type !== "default"
   const percent = kind !== "line" && type === "percent"
@@ -1593,9 +1791,9 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
   // `barOptions.targetKey` (a target per bar) takes over from the single `target` line.
   const perBarTarget = kind === "bar" && Boolean(targetKey)
   const hasTarget = !perBarTarget && target !== undefined && Number.isFinite(target)
-  const targetText = hasTarget ? (targetLabel ?? `目標 ${axisFormatter(target)}`) : ""
+  const targetText = hasTarget ? (targetLabel ?? `${text.target} ${axisFormatter(target)}`) : ""
   const highlightText = (value: number) =>
-    shareHighlight ? `${Math.round(value)}%` : `${stackTotals ? `${STACK_TOTAL_LABEL} ` : ""}${axisFormatter(value)}`
+    shareHighlight ? `${Math.round(value)}%` : `${stackTotals ? `${text.total} ` : ""}${axisFormatter(value)}`
   /** Whether `p`'s label sits within the target's value band and under the target label (at the right end). */
   const nearTargetLabel = (p: HighlightPoint, side: "under" | "over") => {
     if (!hasTarget || !plotWidth || kind === "bar" || labels.length < 2) return false
@@ -1621,7 +1819,7 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
   // One series (or a stack, against its total) can be compared to a target; grouped series and 100% stacks cannot.
   const barTargets: (number | null)[] | null =
     perBarTarget && targetKey && !percent && (stacked || categories.length === 1) ? barTargetValues(data, targetKey) : null
-  const barTargetName = targetLabel ?? BAR_TARGET_LABEL
+  const barTargetName = targetLabel ?? text.target
   const barTargetColor = labelColor ?? guideColor
 
   const markPointFor = (c: number, color: string | undefined) =>
@@ -1835,7 +2033,7 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
   }
 
   /* -- forecast: dashed continuation (+ optional band) of one series */
-  const forecastLabel = forecast?.label ?? DEFAULT_FORECAST_LABEL
+  const forecastLabel = forecast?.label ?? text.forecast
   const forecastBandAlpha = isDarkSurface(labelBackground) ? FORECAST_BAND_ALPHA_DARK : FORECAST_BAND_ALPHA_LIGHT
   const forecastValues: (number | null)[] = []
   if (forecast) {
@@ -2311,7 +2509,7 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
           })
         }
         if (stackTotals && i <= lastActual && rows.length > 1) {
-          rows.push({ name: STACK_TOTAL_LABEL, color: "transparent", value: stackTotals[i] ?? null })
+          rows.push({ name: text.total, color: "transparent", value: stackTotals[i] ?? null })
         }
         const provisional = provStart !== -1 && i >= provStart && i <= lastActual
         if (provisional) {
@@ -2327,19 +2525,19 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
               ...noteFor(at),
             })
           })
-          if (stackTotals && rows.length > 1) rows.push({ name: STACK_TOTAL_LABEL, color: "transparent", value: stackTotals[i] ?? null })
+          if (stackTotals && rows.length > 1) rows.push({ name: text.total, color: "transparent", value: stackTotals[i] ?? null })
         }
         const title = tooltipTitles[i] ?? labels[i] ?? ""
         const lines: string[] = []
         if (barTargets && i <= lastActual) {
           const total = stackTotals ? (stackTotals[i] ?? null) : (values[0]?.[i] ?? null)
-          const note = barTargetNote(barTargetName, total, barTargets[i] ?? null, valueFormatter)
+          const note = barTargetNote(barTargetName, total, barTargets[i] ?? null, valueFormatter, locale)
           if (note) lines.push(note)
         }
         for (const note of notes) {
           if (note.to === undefined ? note.from === i : note.from <= i && i <= note.to) lines.push(note.label)
         }
-        return tooltipHtml(provisional ? `${title}(${provisionalLabel})` : title, rows, valueFormatter, lines)
+        return tooltipHtml(provisional ? text.provisionalTitle(title, provisionalLabel) : title, rows, valueFormatter, lines, locale)
       },
     },
     xAxis: horizontalBars ? valueAxis : categoryAxis,
@@ -2431,8 +2629,6 @@ interface DonutOptionSlice {
 /** How many of the largest slices get an outside label (「自然検索 41%」) by default. */
 const DONUT_OUTSIDE_LABELS = 2
 
-const DEFAULT_TOTAL_LABEL = "合計"
-
 const sliceValue = (value: number) => (Number.isFinite(value) && value > 0 ? value : 0)
 
 /** A slice's share of `total` as text: whole percent, `<1%` for a sliver, `0%` for nothing. */
@@ -2465,15 +2661,16 @@ function donutLegendItems(slices: readonly DonutOptionSlice[]): DonutLegendItem[
 }
 
 /**
- * The default center label: what is totalled (「合計」), the formatted total
+ * The default center label: what is totalled (「合計」 / "Total" in `locale`, default the page's), the formatted total
  * (`amount`, the big line), the unit (a small line under it) and both as one
  * string (`value`, 「9.2万 セッション」).
  */
 function donutCenterText(
   total: number,
   valueFormatter: (value: number) => string,
-  { totalLabel = DEFAULT_TOTAL_LABEL, unit }: { totalLabel?: string; unit?: string } = {},
+  { totalLabel, unit, locale }: { totalLabel?: string; unit?: string; locale?: string } = {},
 ): { label: string; value: string; amount: string; unit?: string } {
+  totalLabel ??= chartText(locale).total
   const amount = valueFormatter(total)
   return { label: totalLabel, value: unit ? `${amount} ${unit}` : amount, amount, ...(unit ? { unit } : {}) }
 }
@@ -2701,8 +2898,10 @@ function hasLabel(labels: Readonly<Record<string, string>> | undefined, key: str
 
 /* ------------------------------------------------------------ provisional */
 
-/** The default label for points that are not final yet. */
-const DEFAULT_PROVISIONAL_LABEL = "速報"
+/** The default label for points that are not final yet, in `locale`: "Preliminary" / 「速報」. Default the page's locale. */
+function defaultProvisionalLabel(locale?: string): string {
+  return chartText(locale).provisional
+}
 
 /**
  * Position of the first provisional point: the first entry of `indexValues`
@@ -2840,9 +3039,10 @@ function resolveValueFormatter(
 function resolveAxisFormatter(
   valueFormatter: ValueFormatter | undefined,
   format: ValueFormat | undefined,
-  locale: string = DEFAULT_LOCALE,
+  localeArg?: string,
 ): ValueFormatter {
   if (valueFormatter) return valueFormatter
+  const locale = resolveLocale(localeArg)
   const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
   if (spec.type !== "compact" && spec.type !== "number" && spec.type !== "currency") return toValueFormatter(format, locale)
   const currency = "currency" in spec ? spec.currency : undefined
@@ -2851,40 +3051,75 @@ function resolveAxisFormatter(
   return (value) => formatValue(value, short, locale)
 }
 
-/** The unit words of a ja number (`1.2万` / `3.4億` / `1兆`) and their sizes, largest first. */
-const JA_UNITS = [
-  { char: "兆", size: 1e12 },
-  { char: "億", size: 1e8 },
-  { char: "万", size: 1e4 },
-] as const
+interface CompactUnit {
+  token: string
+  size: number
+}
 
-const JA_NUMBER_TOKEN_RE = /\d[\d,]*(?:\.\d+)?(?:兆|億|万)?/
+const compactUnitCache = new Map<string, CompactUnit[] | null>()
+
+/**
+ * The compact-notation unit words of a locale and their sizes, largest first: `兆` / `億` / `万` in ja,
+ * `T` / `B` / `M` / `K` in en. `null` when the locale's compact form puts anything between the number and its
+ * word (`1,5 Mio.`), where a token cannot be swapped in place.
+ */
+function compactUnits(locale: string): CompactUnit[] | null {
+  const cached = compactUnitCache.get(locale)
+  if (cached !== undefined) return cached
+  let units: CompactUnit[] | null = []
+  try {
+    const compact = new Intl.NumberFormat(locale, { notation: "compact" })
+    const seen = new Set<string>()
+    for (let exp = 3; exp <= 15; exp++) {
+      const parts = compact.formatToParts(10 ** exp)
+      const at = parts.findIndex((p) => p.type === "compact")
+      if (at === -1) continue
+      if (parts[at - 1]?.type !== "integer" || at !== parts.length - 1) {
+        units = null
+        break
+      }
+      const token = parts[at]!.value
+      if (seen.has(token)) continue
+      seen.add(token)
+      units.push({ token, size: 10 ** exp })
+    }
+  } catch {
+    units = null
+  }
+  const sorted = units && units.length > 0 ? units.sort((a, b) => b.size - a.size) : null
+  compactUnitCache.set(locale, sorted)
+  return sorted
+}
+
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 /**
  * The value-axis tick formatter for an axis whose largest tick is `top`: every tick reads in the unit of
- * that largest tick, so 万 and 億 never mix on one axis (`¥0.5億` / `¥1億` / `¥1.5億`, not `¥5,000万` / `¥1億`).
- * Only the ja short forms (`compact` / `number` / `currency`, no `valueFormatter`) have units to align;
- * any other format — and an axis whose largest tick is under 1万 — keeps `resolveAxisFormatter`'s output as it is.
+ * that largest tick, so units never mix on one axis (`¥0.5億` / `¥1億` / `¥1.5億`, not `¥5,000万` / `¥1億`;
+ * `$0.5M` / `$1M` / `$1.5M`, not `$500K` / `$1M`). Only the short forms (`compact` / `number` / `currency`,
+ * no `valueFormatter`) have units to align; any other format — an axis whose largest tick is under the smallest
+ * unit (1万 / 1K), or a locale whose compact form cannot be aligned in place — keeps `resolveAxisFormatter`'s output as it is.
  */
 function resolveAxisTickFormatter(
   valueFormatter: ValueFormatter | undefined,
   format: ValueFormat | undefined,
-  locale: string = DEFAULT_LOCALE,
+  localeArg?: string,
 ): (top: number) => ValueFormatter {
+  const locale = resolveLocale(localeArg)
   const base = resolveAxisFormatter(valueFormatter, format, locale)
   const spec = format === undefined ? { type: "compact" as const } : typeof format === "string" ? { type: format } : format
-  const aligns =
-    !valueFormatter && locale.toLowerCase().startsWith("ja") && (spec.type === "compact" || spec.type === "number" || spec.type === "currency")
-  if (!aligns) return () => base
+  const units = !valueFormatter && (spec.type === "compact" || spec.type === "number" || spec.type === "currency") ? compactUnits(locale) : null
+  if (!units) return () => base
   const number = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 })
+  const numberToken = new RegExp(`\\d[\\d,]*(?:\\.\\d+)?(?:${units.map((u) => escapeRegExp(u.token)).join("|")})?`)
   return (top) => {
-    const unit = JA_UNITS.find((u) => Math.abs(top) >= u.size)
+    const unit = units.find((u) => Math.abs(top) >= u.size)
     if (!unit) return base
     return (value) => {
       const text = base(value)
       if (value === 0 || !Number.isFinite(value)) return text
-      const scaled = `${number.format(Math.abs(value) / unit.size)}${unit.char}`
-      return text.replace(JA_NUMBER_TOKEN_RE, () => scaled)
+      const scaled = `${number.format(Math.abs(value) / unit.size)}${unit.token}`
+      return text.replace(numberToken, () => scaled)
     }
   }
 }
@@ -2913,8 +3148,20 @@ function clamp(value: number, min: number, max: number): number {
 /** How many categories a chart colours individually; the rest fold into「その他」. */
 const MAX_CHART_SERIES = 5
 
-/** The series name the folded categories get. */
-const OTHER_SERIES_LABEL = "その他"
+/** The series name the folded categories get, by language. */
+const OTHER_SERIES_LABELS: Record<UiLanguage, string> = { ja: "その他", en: "Other" }
+
+/** The series name the folded categories get in `locale` ("Other" / "その他"). Default the page's locale (`<html lang>`). */
+function otherSeriesLabel(locale?: string): string {
+  return OTHER_SERIES_LABELS[uiLanguage(resolveLocale(locale))]
+}
+
+const OTHER_NAMES = new Set(Object.values(OTHER_SERIES_LABELS))
+
+/** Whether a category / row is the "other" bucket by name (「その他」 or "Other", whatever the page language). */
+function isOtherName(name: string | null | undefined): boolean {
+  return typeof name === "string" && OTHER_NAMES.has(name)
+}
 
 interface AggregatedItems<Item extends { name: string; value: number }> {
   /** The `n` largest items, in their given order. All items when there are `n` or fewer. */
@@ -2934,7 +3181,7 @@ interface AggregatedItems<Item extends { name: string; value: number }> {
 function aggregateTopN<Item extends { name: string; value: number }>(
   items: readonly Item[],
   n: number = MAX_CHART_SERIES,
-  otherLabel: string = OTHER_SERIES_LABEL,
+  otherLabel: string = otherSeriesLabel(),
 ): AggregatedItems<Item> {
   if (items.length <= n) return { top: [...items], rest: [], other: null }
   const ranked = items
@@ -2963,7 +3210,7 @@ function aggregateSeries(
   data: readonly Record<string, unknown>[],
   categories: readonly string[],
   n: number = MAX_CHART_SERIES,
-  otherLabel: string = OTHER_SERIES_LABEL,
+  otherLabel: string = otherSeriesLabel(),
 ): AggregatedSeries {
   const totals = categories.map((name) => ({
     name,
@@ -2995,12 +3242,14 @@ function aggregateSeriesKeeping(
   categories: readonly string[],
   keep: string | undefined,
   n: number = MAX_CHART_SERIES,
+  otherLabel: string = otherSeriesLabel(),
 ): AggregatedSeries {
-  if (keep === undefined || !categories.includes(keep)) return aggregateSeries(data, categories, n)
+  if (keep === undefined || !categories.includes(keep)) return aggregateSeries(data, categories, n, otherLabel)
   const aggregated = aggregateSeries(
     data,
     categories.filter((c) => c !== keep),
     n,
+    otherLabel,
   )
   return { ...aggregated, categories: [...aggregated.categories, keep] }
 }
@@ -3036,7 +3285,7 @@ function seriesColorsWithComparison(
  * Colour per drawn series: the record's token for that category, else the
  * array's token at the category's position in `allCategories` (cycled), else
  * the token palette by drawn position. `otherCategory` — and a category the
- * data itself names「その他」(`OTHER_SERIES_LABEL`) — always gets `otherColor`.
+ * data itself names「その他」/ "Other" (`OTHER_SERIES_LABELS`) — always gets `otherColor`.
  */
 function seriesColorsFor(
   categories: readonly string[],
@@ -3048,7 +3297,7 @@ function seriesColorsFor(
   const list = Array.isArray(colors) ? (colors as ChartSeriesColor[]) : undefined
   const record = !Array.isArray(colors) && colors ? (colors as Partial<Record<string, ChartSeriesColor>>) : undefined
   return categories.map((category, i) => {
-    if ((otherCategory !== null && category === otherCategory) || category === OTHER_SERIES_LABEL) return otherColor
+    if ((otherCategory !== null && category === otherCategory) || isOtherName(category)) return otherColor
     const fromRecord = record?.[category]
     if (fromRecord) return fromRecord
     if (list && list.length > 0) {
@@ -3095,7 +3344,7 @@ interface DonutSlicesConfig {
  */
 function donutSlices(
   data: readonly Record<string, unknown>[],
-  { index, value, colors, maxSlices = MAX_CHART_SERIES, otherColor, otherLabel = OTHER_SERIES_LABEL }: DonutSlicesConfig,
+  { index, value, colors, maxSlices = MAX_CHART_SERIES, otherColor, otherLabel = otherSeriesLabel() }: DonutSlicesConfig,
 ): DonutSlice[] {
   const items = data
     .map((row, i) => {
@@ -3108,7 +3357,8 @@ function donutSlices(
   const slices: DonutSlice[] = top.map((item, rank) => ({
     name: item.name,
     value: item.value,
-    color: palette[rank % palette.length]!,
+    // A row the data itself names「その他」/ "Other" is the same remainder: grey, like the folded slice.
+    color: isOtherName(item.name) ? otherColor : palette[rank % palette.length]!,
     isOther: false,
     row: item.row,
   }))
@@ -3181,7 +3431,7 @@ interface BarListRowsConfig extends BarListOptions {
  */
 function barListRows<Row extends object>(
   data: readonly Row[],
-  { index = "name", category = "value", sortOrder = "descending", maxItems = MAX_CHART_SERIES, otherLabel = OTHER_SERIES_LABEL, exclude }: BarListRowsConfig = {},
+  { index = "name", category = "value", sortOrder = "descending", maxItems = MAX_CHART_SERIES, otherLabel = otherSeriesLabel(), exclude }: BarListRowsConfig = {},
 ): BarListRow<Row>[] {
   const items = data.map((row): BarListRow<Row> => {
     const cells = row as Record<string, unknown>
@@ -3227,19 +3477,21 @@ const BAR_LIST_OTHER_TINT = 30
 
 /**
  * The fill of each BarList row: all real rows in the same tint of `color`
- * (`BAR_LIST_TINT`), the folded「その他」row in a tint of `otherColor`
+ * (`BAR_LIST_TINT`), the folded「その他」row (and a row the data names「その他」/ "Other") in a tint of `otherColor`
  * (`BAR_LIST_OTHER_TINT`) — the palest fill, a remainder never outweighs a
  * ranked row. A legacy per-row `color` (or a threshold tone) replaces `color`
  * for that row. A tint, not the solid token, so the label printed over the bar
  * keeps its contrast.
  */
 function barListFills(
-  rows: readonly Pick<BarListRow, "isOther" | "color">[],
+  rows: readonly (Pick<BarListRow, "isOther" | "color"> & { name?: string })[],
   color: ChartColor,
   otherColor: string,
 ): string[] {
   return rows.map((row) =>
-    row.isOther ? tintCss(otherColor, BAR_LIST_OTHER_TINT) : tintCss(chartColorToCss(row.color ?? color), BAR_LIST_TINT),
+    row.isOther || isOtherName(row.name)
+      ? tintCss(otherColor, BAR_LIST_OTHER_TINT)
+      : tintCss(chartColorToCss(row.color ?? color), BAR_LIST_TINT),
   )
 }
 
@@ -3455,11 +3707,30 @@ interface ChartSummaryInput {
   format?: ValueFormat
   /** Wins over `format`. */
   valueFormatter?: ValueFormatter
+  /** Language of the sentence. Default the page's locale (`<html lang>`). */
+  locale?: string
+}
+
+const SUMMARY_TEXT = {
+  ja: {
+    up: "、前の点より増加",
+    down: "、前の点より減少",
+    flat: "、前の点と横ばい",
+    latest: (label: string, value: string) => `最新 ${label} は ${value}`,
+    top: (name: string, share: string) => `最大は ${name}(${share})`,
+  },
+  en: {
+    up: ", up from the previous point",
+    down: ", down from the previous point",
+    flat: ", flat from the previous point",
+    latest: (label: string, value: string) => `Latest ${label}: ${value}`,
+    top: (name: string, share: string) => `Largest: ${name} (${share})`,
+  },
 }
 
 /**
  * One-sentence summary built from the rows, for `summary="auto"`:
- * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」. The direction is
+ * 「<title>: 最新 <index> は <値>、前の点より増加/減少/横ばい」("<title>: Latest <index>: <value>, up from the previous point"). The direction is
  * computed from the last two non-empty points of the first series — never
  * written by hand, so it cannot contradict the data. `undefined` when there is
  * no usable point.
@@ -3475,26 +3746,29 @@ function buildChartSummary(input: ChartSummaryInput): string | undefined {
   }
   const latest = points[points.length - 1]
   if (!latest) return undefined
-  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact")
+  const locale = resolveLocale(input.locale)
+  const t = SUMMARY_TEXT[uiLanguage(locale)]
+  const text = input.valueFormatter ?? toValueFormatter(input.format ?? "compact", locale)
   const prev = points[points.length - 2]
-  const direction = !prev ? "" : latest.value > prev.value ? "、前の点より増加" : latest.value < prev.value ? "、前の点より減少" : "、前の点と横ばい"
+  const direction = !prev ? "" : latest.value > prev.value ? t.up : latest.value < prev.value ? t.down : t.flat
   const head = input.title ? `${input.title}: ` : ""
-  return `${head}最新 ${latest.label} は ${text(latest.value)}${direction}`
+  return `${head}${t.latest(latest.label, text(latest.value))}${direction}`
 }
 
 /**
- * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」 from the slices
- * (largest first). `undefined` when there is nothing to describe.
+ * `summary="auto"` for a donut: 「<title>: 最大は <名前>(<構成比>)」("<title>: Largest: <name> (<share>)") from the slices
+ * (largest first). `undefined` when there is nothing to describe. `locale` picks the language; default the page's.
  */
 function buildShareSummary(
   slices: readonly { name: string; value: number }[],
   title?: string,
+  locale?: string,
 ): string | undefined {
   const total = slices.reduce((sum, s) => sum + s.value, 0)
   const top = slices[0]
   if (!top || total <= 0) return undefined
   const share = `${Math.round((top.value / total) * 1000) / 10}%`
-  return `${title ? `${title}: ` : ""}最大は ${top.name}(${share})`
+  return `${title ? `${title}: ` : ""}${SUMMARY_TEXT[uiLanguage(resolveLocale(locale))].top(top.name, share)}`
 }
 
 /* ---------- end of inlined code ---------- */
@@ -3561,6 +3835,47 @@ export interface WaterfallChartProps<T extends Record<string, unknown> = Record<
 
 /* ------------------------------------------------------------------ model */
 
+const TEXT = {
+  ja: {
+    net: "純増",
+    total: "合計",
+    change: "増減",
+    cumulative: "累計",
+    cumulativeChange: "累計増減",
+    item: "項目",
+    start: "開始",
+    end: "終了",
+    fromTo: (from: string, to: string, net: string) => `${from} → ${to}（${net}）`,
+    from: (from: string, net: string) => `${from} から ${net}`,
+    to: (to: string, net: string) => `${to}（${net}）`,
+    netOnly: (net: string) => `増減の合計 ${net}`,
+    increase: (name: string, value: string) => `最大の増加は ${name}（${value}）`,
+    decrease: (name: string, value: string) => `最大の減少は ${name}（${value}）`,
+    sentenceJoin: "。",
+    chart: (label: string) => `${label}のウォーターフォールチャート`,
+  },
+  en: {
+    net: "Net change",
+    total: "Total",
+    change: "Change",
+    cumulative: "Cumulative",
+    cumulativeChange: "Cumulative change",
+    item: "Item",
+    start: "Start",
+    end: "End",
+    fromTo: (from: string, to: string, net: string) => `${from} → ${to} (${net})`,
+    from: (from: string, net: string) => `${net} from ${from}`,
+    to: (to: string, net: string) => `${to} (${net})`,
+    netOnly: (net: string) => `Net change ${net}`,
+    increase: (name: string, value: string) => `Largest increase: ${name} (${value})`,
+    decrease: (name: string, value: string) => `Largest decrease: ${name} (${value})`,
+    sentenceJoin: ". ",
+    chart: (label: string) => `Waterfall chart of ${label}`,
+  },
+}
+
+const textOf = (locale?: string) => TEXT[uiLanguage(resolveLocale(locale))]
+
 export type WaterfallKind = "total" | "increase" | "decrease" | "flat" | "gap"
 
 export interface WaterfallStep {
@@ -3582,7 +3897,7 @@ export interface WaterfallStep {
  */
 export function waterfallSteps(
   data: readonly Record<string, unknown>[],
-  config: { index: string; value: string; totals?: readonly string[]; mode?: WaterfallMode },
+  config: { index: string; value: string; totals?: readonly string[]; mode?: WaterfallMode; locale?: string },
 ): WaterfallStep[] {
   const totals = new Set(config.totals ?? [])
   const delta = config.mode === "delta"
@@ -3603,13 +3918,15 @@ export function waterfallSteps(
   })
   // `delta`: the net change closes the plot as a total bar from 0 (series colour 1), so the moves add up to something.
   if (delta && steps.some((s) => s.kind !== "gap")) {
-    steps.push({ name: DELTA_TOTAL_NAME, kind: "total", value: running, start: 0, end: running, row: {} })
+    steps.push({ name: deltaTotalName(config.locale), kind: "total", value: running, start: 0, end: running, row: {} })
   }
   return steps
 }
 
-/** The name of the net-change bar that `mode="delta"` appends. */
-export const DELTA_TOTAL_NAME = "純増"
+/** The name of the net-change bar that `mode="delta"` appends, in `locale` ("Net change" / 「純増」). Default the page's locale. */
+export function deltaTotalName(locale?: string): string {
+  return textOf(locale).net
+}
 
 /** What `mode="delta"` leaves out of the bars: the opening / closing totals and the net change of the moves. */
 export interface WaterfallDeltaEnds {
@@ -3647,16 +3964,22 @@ export function waterfallDeltaEnds(
 }
 
 /** The note above a delta plot: `前期 ¥2.2億 → 当期 ¥2.2億（+¥130万）`; without the totals' values, the net change alone. */
-export function waterfallDeltaNote(ends: WaterfallDeltaEnds, formatter: ValueFormatter, labels?: Record<string, string>): string {
+export function waterfallDeltaNote(
+  ends: WaterfallDeltaEnds,
+  formatter: ValueFormatter,
+  labels?: Record<string, string>,
+  locale?: string,
+): string {
+  const t = textOf(locale)
   const net = signedText(ends.net, formatter)
   const { opening, closing } = ends
   const side = (e: { name: string; value: number | null } | null) => (e && e.value !== null ? `${labelOf(e.name, labels)} ${formatter(e.value)}` : null)
   const from = side(opening)
   const to = side(closing)
-  if (from && to) return `${from} → ${to}（${net}）`
-  if (from) return `${from} から ${net}`
-  if (to) return `${to}（${net}）`
-  return `増減の合計 ${net}`
+  if (from && to) return t.fromTo(from, to, net)
+  if (from) return t.from(from, net)
+  if (to) return t.to(to, net)
+  return t.netOnly(net)
 }
 
 export interface WaterfallStack {
@@ -3740,7 +4063,9 @@ export function buildWaterfallSummary(
   title?: string,
   labels?: Record<string, string>,
   delta?: WaterfallDeltaEnds,
+  locale?: string,
 ): string | undefined {
+  const t = textOf(locale)
   const real = steps.filter((s) => s.kind !== "gap")
   const first = real[0]
   const last = real[real.length - 1]
@@ -3750,7 +4075,7 @@ export function buildWaterfallSummary(
   // A first step starts at 0, so its end is its value; a total's end is the total. `delta`: the note (totals and net change) instead.
   const parts = [
     delta
-      ? waterfallDeltaNote(delta, formatter, labels)
+      ? waterfallDeltaNote(delta, formatter, labels, locale)
       : real.length === 1
         ? `${name(first)} ${formatter(first.end)}`
         : `${name(first)} ${formatter(first.end)} → ${name(last)} ${formatter(last.end)}`,
@@ -3761,9 +4086,9 @@ export function buildWaterfallSummary(
     if (s.kind === "increase" && (!up || s.value! > up.value!)) up = s
     if (s.kind === "decrease" && (!down || s.value! < down.value!)) down = s
   }
-  if (up) parts.push(`最大の増加は ${name(up)}（${signedText(up.value!, formatter)}）`)
-  if (down) parts.push(`最大の減少は ${name(down)}（${signedText(down.value!, formatter)}）`)
-  return `${head}${parts.join("。")}`
+  if (up) parts.push(t.increase(name(up), signedText(up.value!, formatter)))
+  if (down) parts.push(t.decrease(name(down), signedText(down.value!, formatter)))
+  return `${head}${parts.join(t.sentenceJoin)}`
 }
 
 /** The screen-reader table: one row per step with its change and the running total. */
@@ -3773,19 +4098,21 @@ export function waterfallDataTable(
   formatter: ValueFormatter,
   labels?: Record<string, string>,
   delta?: WaterfallDeltaEnds,
+  locale?: string,
 ): ChartDataTable {
+  const t = textOf(locale)
   const label = (key: string) => labelOf(key, labels)
   const rows = steps.map((s) => [
     label(s.name),
-    s.kind === "total" ? (delta ? DELTA_TOTAL_NAME : "合計") : s.value === null ? EMPTY_VALUE : signedText(s.value, formatter),
+    s.kind === "total" ? (delta ? t.net : t.total) : s.value === null ? EMPTY_VALUE : signedText(s.value, formatter),
     s.kind === "gap" ? EMPTY_VALUE : delta ? signedText(s.end, formatter) : formatter(s.end),
   ])
   // `delta`: the totals are not bars, so the opening / closing values are rows of their own (they are not in `steps`).
   const end = (e: WaterfallDeltaEnds["opening"], role: string) =>
     e && e.value !== null ? [[label(e.name), role, formatter(e.value)]] : []
   return {
-    columns: [labels?.[names.index] ?? "項目", "増減", delta ? "累計増減" : "累計"],
-    rows: delta ? [...end(delta.opening, "開始"), ...rows, ...end(delta.closing, "終了")] : rows,
+    columns: [labels?.[names.index] ?? t.item, t.change, delta ? t.cumulativeChange : t.cumulative],
+    rows: delta ? [...end(delta.opening, t.start), ...rows, ...end(delta.closing, t.end)] : rows,
   }
 }
 
@@ -3820,6 +4147,8 @@ export interface WaterfallOptionConfig {
   noteColor?: string
   /** Colour of the 1px line joining the bars' tops (the border token). `undefined` draws no connector. */
   connectorColor?: string
+  /** Language of the tooltip. Default the page's locale (`<html lang>`). */
+  locale?: string
 }
 
 /** The bar fills 45% of its category band. ECharts reads `barCategoryGap` as a share of the band (not of the bar), so the gap is the other 55%; a gap over 100% leaves the bar at its 1px minimum. */
@@ -3960,6 +4289,7 @@ const ROW_STYLE = "display:flex;align-items:center;gap:8px;line-height:20px"
 /** The ECharts option: a transparent base plus the part above and below 0, coloured per step. */
 export function buildWaterfallOption(config: WaterfallOptionConfig): EChartsOption {
   const { steps, colors, polarity, labels, valueFormatter, showValues = true, showTooltip = true } = config
+  const t = textOf(config.locale)
   const delta = config.mode === "delta"
   const axisFormatter = config.axisFormatter ?? valueFormatter
   const noteWidth = config.plotWidth ? Math.max(120, config.plotWidth - 16) : undefined
@@ -4041,9 +4371,13 @@ export function buildWaterfallOption(config: WaterfallOptionConfig): EChartsOpti
           `<span style="font-weight:500;font-variant-numeric:tabular-nums;margin-left:12px">${escapeHtml(text)}</span></div>`
         const rows =
           step.kind === "total"
-            ? line(delta ? DELTA_TOTAL_NAME : "合計", delta ? signedText(step.end, valueFormatter) : valueFormatter(step.end))
-            : line("増減", waterfallStepText(step, valueFormatter)) +
-              (step.kind === "gap" ? "" : delta ? line("累計増減", signedText(step.end, valueFormatter)) : line("累計", valueFormatter(step.end)))
+            ? line(delta ? t.net : t.total, delta ? signedText(step.end, valueFormatter) : valueFormatter(step.end))
+            : line(t.change, waterfallStepText(step, valueFormatter)) +
+              (step.kind === "gap"
+                ? ""
+                : delta
+                  ? line(t.cumulativeChange, signedText(step.end, valueFormatter))
+                  : line(t.cumulative, valueFormatter(step.end)))
         return `<div style="font-weight:500;margin-bottom:4px">${escapeHtml(labelOf(step.name, labels))}</div>${rows}`
       },
     },
@@ -4141,14 +4475,17 @@ function WaterfallChartImpl<T extends Record<string, unknown>>(
   ref: ForwardedRef<HTMLDivElement>,
 ) {
   const valueKey: string = categories[0] ?? ""
-  const tokens = useChartTokens()
-  const { ref: frameRef, width: plotWidth } = useChartSurface(ref, tokens)
+  const { ref: frameRef, width: plotWidth, tokens } = useChartSurface(ref)
   // Value labels and the tooltip read in full (as `format` says); ticks read short.
-  const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format), [valueFormatterProp, format])
-  const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatterProp, format), [valueFormatterProp, format])
-  const steps = useMemo(() => waterfallSteps(data, { index, value: valueKey, totals, mode }), [data, index, valueKey, totals, mode])
+  const locale = useLocale()
+  const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format, locale), [valueFormatterProp, format, locale])
+  const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatterProp, format, locale), [valueFormatterProp, format, locale])
+  const steps = useMemo(
+    () => waterfallSteps(data, { index, value: valueKey, totals, mode, locale }),
+    [data, index, valueKey, totals, mode, locale],
+  )
   const ends = useMemo(() => (mode === "delta" ? waterfallDeltaEnds(data, { index, value: valueKey, totals }) : undefined), [data, index, valueKey, totals, mode])
-  const deltaNote = useMemo(() => (ends ? waterfallDeltaNote(ends, valueFormatter, labels) : undefined), [ends, valueFormatter, labels])
+  const deltaNote = useMemo(() => (ends ? waterfallDeltaNote(ends, valueFormatter, labels, locale) : undefined), [ends, valueFormatter, labels, locale])
   const colors = useMemo(() => {
     const fills = resolveFillColors(tokens)
     const [total = ""] = resolveChartColors(["chart-1"], tokens)
@@ -4181,18 +4518,20 @@ function WaterfallChartImpl<T extends Record<string, unknown>>(
         minValue,
         maxValue,
         yAxisWidth,
+        locale,
       }),
-    [steps, colors, polarity, labels, valueFormatter, axisFormatter, showValues, showTooltip, tokens, mode, deltaNote, plotWidth, chartOptions, minValue, maxValue, yAxisWidth],
+    [steps, colors, polarity, labels, valueFormatter, axisFormatter, showValues, showTooltip, tokens, mode, deltaNote, plotWidth, chartOptions, minValue, maxValue, yAxisWidth, locale],
   )
   const dataTable = useMemo(
-    () => waterfallDataTable(steps, { index, value: valueKey }, valueFormatter, labels, ends),
-    [steps, index, valueKey, valueFormatter, labels, ends],
+    () => waterfallDataTable(steps, { index, value: valueKey }, valueFormatter, labels, ends, locale),
+    [steps, index, valueKey, valueFormatter, labels, ends, locale],
   )
   const resolvedSummary = useMemo(
-    () => (summary === "auto" ? buildWaterfallSummary(steps, valueFormatter, title, labels, ends) : summary),
-    [summary, steps, valueFormatter, title, labels, ends],
+    () => (summary === "auto" ? buildWaterfallSummary(steps, valueFormatter, title, labels, ends, locale) : summary),
+    [summary, steps, valueFormatter, title, labels, ends, locale],
   )
-  const label = ariaLabel ?? `${labelOf(valueKey, labels) || "増減"}のウォーターフォールチャート`
+  const t = textOf(locale)
+  const label = ariaLabel ?? t.chart(labelOf(valueKey, labels) || t.change.toLowerCase())
   return (
     <ChartFrame
       {...chartRootProps(rest)}