@linxiraos/pi-stats 1.1.26 → 1.2.0

package/src/client/data/live.tsx

@@ -3,21 +3,17 @@
  * version every query revalidates against, background ingest progress, and
  * the rollup indexing backlog.
  *
- * Any component can `useLive()`; queries (see `useQuery`) refetch whenever
- * `version` advances, so rows ingested in the background repaint the active
- * page without a manual refresh.
+ * The state lives in a module store read through narrow selectors, so a
+ * progress tick only re-renders what shows progress: `useLiveVersion()` for
+ * queries (see `useQuery`), `useLiveStatus()` for the chrome.
  */
 
-import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { type ReactNode, useEffect, useSyncExternalStore } from "react";
 import * as api from "../api";
 import type { LiveStatus, LiveSyncStatus } from "../types";
 
-export interface LiveState {
-	/**
-	 * Client-side data version; bumps whenever the server's version changes
-	 * (including after reconnecting to a restarted server).
-	 */
-	version: number;
+/** Ingest status shown by the chrome. */
+export interface LiveStatusView {
 	sync: LiveSyncStatus;
 	/** Hours whose rollups are still being built; wide ranges may be incomplete. */
 	indexingHours: number;
@@ -36,50 +32,94 @@ const IDLE_SYNC: LiveSyncStatus = {
 	error: null,
 };
 
-const LiveContext = createContext<LiveState>({
-	version: 0,
-	sync: IDLE_SYNC,
-	indexingHours: 0,
-	connected: false,
-	requestSync: () => {},
-});
+function requestSync(): void {
+	api.requestSync().catch(() => {});
+}
 
-export function LiveProvider({ children }: { children: ReactNode }) {
-	const [status, setStatus] = useState<{ server: LiveStatus | null; version: number }>({ server: null, version: 0 });
-	const [connected, setConnected] = useState(false);
+let lastServerVersion: number | null = null;
+/** Distinct server versions seen (including across server restarts). */
+let seenVersions = 0;
+/**
+ * Client-side data version; bumps whenever the server's version changes.
+ * Lags `seenVersions` by one so the first stream message doesn't refetch what
+ * just loaded.
+ */
+let version = 0;
+let status: LiveStatusView = { sync: IDLE_SYNC, indexingHours: 0, connected: false, requestSync };
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+function emit(): void {
+	for (const listener of listeners) listener();
+}
+
+function sameSync(a: LiveSyncStatus, b: LiveSyncStatus): boolean {
+	return (
+		a.phase === b.phase &&
+		a.current === b.current &&
+		a.total === b.total &&
+		a.processed === b.processed &&
+		a.lastSyncedAt === b.lastSyncedAt &&
+		a.error === b.error
+	);
+}
+
+function receive(next: LiveStatus): void {
+	if (lastServerVersion !== next.version) {
+		lastServerVersion = next.version;
+		seenVersions++;
+	}
+	const nextVersion = Math.max(0, seenVersions - 1);
+	const statusChanged = next.indexingHours !== status.indexingHours || !sameSync(next.sync, status.sync);
+	if (!statusChanged && nextVersion === version) return;
+	version = nextVersion;
+	if (statusChanged) status = { ...status, sync: next.sync, indexingHours: next.indexingHours };
+	emit();
+}
 
+function setConnected(connected: boolean): void {
+	if (connected === status.connected) return;
+	status = { ...status, connected };
+	emit();
+}
+
+const getStatus = (): LiveStatusView => status;
+const getVersion = (): number => version;
+const getDisabledVersion = (): number => -1;
+
+/** Current data version, read outside render (e.g. when a fetch starts). */
+export function currentLiveVersion(): number {
+	return version;
+}
+
+/** Owns the `/api/events` stream; mount once at the app root. */
+export function LiveProvider({ children }: { children: ReactNode }) {
 	useEffect(() => {
 		const source = new EventSource("/api/events");
 		source.onopen = () => setConnected(true);
 		source.onerror = () => setConnected(false);
-		source.onmessage = event => {
-			const next = JSON.parse(event.data) as LiveStatus;
-			setStatus(prev => ({
-				server: next,
-				version: prev.server && prev.server.version === next.version ? prev.version : prev.version + 1,
-			}));
+		source.onmessage = event => receive(JSON.parse(event.data) as LiveStatus);
+		return () => {
+			source.close();
+			setConnected(false);
 		};
-		return () => source.close();
-	}, []);
-
-	const requestSync = useCallback(() => {
-		api.requestSync().catch(() => {});
 	}, []);
+	return children;
+}
 
-	const value = useMemo<LiveState>(
-		() => ({
-			// Start at 0 so the first stream message (version 1) doesn't refetch what just loaded.
-			version: Math.max(0, status.version - 1),
-			sync: status.server?.sync ?? IDLE_SYNC,
-			indexingHours: status.server?.indexingHours ?? 0,
-			connected,
-			requestSync,
-		}),
-		[status, connected, requestSync],
-	);
-	return <LiveContext.Provider value={value}>{children}</LiveContext.Provider>;
+/** Ingest status for the chrome; data-version bumps alone don't re-render. */
+export function useLiveStatus(): LiveStatusView {
+	return useSyncExternalStore(subscribe, getStatus);
 }
 
-export function useLive(): LiveState {
-	return useContext(LiveContext);
+/**
+ * Data version for queries. Disabled (hidden) consumers read a constant -1 so
+ * live traffic never re-renders them.
+ */
+export function useLiveVersion(enabled = true): number {
+	return useSyncExternalStore(subscribe, enabled ? getVersion : getDisabledVersion);
 }

package/src/client/data/query-store.ts

@@ -0,0 +1,108 @@
+/**
+ * Framework-free query cache behind `useQuery`: per-key cached results in
+ * size-bounded buckets, and one shared in-flight request per key that is
+ * aborted once its last waiter leaves.
+ */
+
+export interface CacheEntry {
+	data: unknown;
+	updatedAt: number;
+	version: number;
+}
+
+interface CacheBucket {
+	entries: Map<string, CacheEntry>;
+	limit: number;
+}
+
+export interface Inflight {
+	promise: Promise<unknown>;
+	controller: AbortController;
+	/** Queries (and prefetches) waiting on this request. */
+	waiters: number;
+}
+
+/** Handed to every fetcher. */
+export interface QueryFetchContext {
+	/** Aborted once no query waits for this request any more. */
+	signal: AbortSignal;
+}
+
+/**
+ * Loads one key's data. `previous` is the cached data for this key, for
+ * conditional revalidation; `undefined` on first load. It is a separate
+ * parameter so fetchers that ignore it still let `T` be inferred from their
+ * return type.
+ */
+export type QueryFetcher<T> = (context: QueryFetchContext, previous: T | undefined) => Promise<T>;
+
+const defaultBucket: CacheBucket = { entries: new Map(), limit: 128 };
+/** Full session traces: MBs each, at most a few worth keeping. */
+const traceBucket: CacheBucket = { entries: new Map(), limit: 4 };
+/** Request detail payloads (full prompts and responses). */
+const requestBucket: CacheBucket = { entries: new Map(), limit: 16 };
+
+const inflight = new Map<string, Inflight>();
+
+function bucketFor(key: string): CacheBucket {
+	if (key.startsWith('["trace",')) return traceBucket;
+	if (key.startsWith('["request",')) return requestBucket;
+	return defaultBucket;
+}
+
+export function cachedEntry(key: string): CacheEntry | undefined {
+	return bucketFor(key).entries.get(key);
+}
+
+/** The shared request currently running for `key`, if any. */
+export function inflightRequest(key: string): Inflight | undefined {
+	return inflight.get(key);
+}
+
+function remember(key: string, entry: CacheEntry): void {
+	const { entries, limit } = bucketFor(key);
+	entries.delete(key);
+	entries.set(key, entry);
+	if (entries.size > limit) {
+		const oldest = entries.keys().next().value;
+		if (oldest !== undefined) entries.delete(oldest);
+	}
+}
+
+/**
+ * Fetch into the cache (tagged with live data `version`), sharing one request
+ * among concurrent callers of the same key. The caller holds one waiter on
+ * the returned request; pair with {@link releaseQuery}.
+ */
+export function loadQuery<T>(key: string, version: number, fetcher: QueryFetcher<T>): Inflight {
+	const pending = inflight.get(key);
+	if (pending) {
+		pending.waiters++;
+		return pending;
+	}
+	const controller = new AbortController();
+	// Entries for a key are only ever written by fetchers of that key's type.
+	const previous = cachedEntry(key)?.data as T | undefined;
+	const request: Inflight = {
+		promise: fetcher({ signal: controller.signal }, previous)
+			.then(data => {
+				remember(key, { data, updatedAt: Date.now(), version });
+				return data;
+			})
+			.finally(() => {
+				if (inflight.get(key) === request) inflight.delete(key);
+			}),
+		controller,
+		waiters: 1,
+	};
+	inflight.set(key, request);
+	return request;
+}
+
+/** Drop one waiter; the last one out aborts the request. */
+export function releaseQuery(key: string, request: Inflight): void {
+	request.waiters--;
+	if (request.waiters > 0) return;
+	if (inflight.get(key) === request) inflight.delete(key);
+	request.controller.abort();
+}

package/src/client/data/query.ts

@@ -2,31 +2,26 @@
  * `useQuery`: cached, live-revalidating data fetching for dashboard pages.
  *
  * - Results are cached per key for the page session, so revisiting a page or
- *   a range renders instantly from memory.
+ *   a range renders instantly from memory. Multi-MB detail payloads (traces,
+ *   request details) live in their own small LRUs so they don't pile up.
  * - A key change keeps the previous key's data on screen (`stale: true`) until
  *   the new data lands, so charts morph instead of flashing skeletons.
  * - Every cached entry remembers the live data version it was fetched at
- *   (see `useLive`); when the version advances, enabled queries refetch in the
- *   background, throttled so a burst of ingest batches costs one request.
- * - Identical keys share one in-flight request.
+ *   (see `useLiveVersion`); when the version advances, enabled queries refetch
+ *   in the background, throttled so a burst of ingest batches costs one request.
+ * - Identical keys share one in-flight request; it is aborted once no query
+ *   waits for it any more.
+ * - Fetchers receive the cached data for their key, so conditional requests
+ *   can resolve to that same object; an unchanged reference does not re-render.
  */
 
 import { startTransition, useCallback, useEffect, useReducer, useRef, useState } from "react";
-import { useLive } from "./live";
+import { currentLiveVersion, useLiveVersion } from "./live";
+import { cachedEntry, type Inflight, inflightRequest, loadQuery, type QueryFetcher, releaseQuery } from "./query-store";
 
-interface CacheEntry {
-	data: unknown;
-	updatedAt: number;
-	version: number;
-}
-
-const CACHE_LIMIT = 128;
 /** Minimum spacing between live-driven refetches of one query. */
 const LIVE_REFETCH_THROTTLE_MS = 1500;
 
-const cache = new Map<string, CacheEntry>();
-const inflight = new Map<string, Promise<unknown>>();
-
 export interface QueryOptions {
 	/** Only enabled queries fetch; hidden (kept-alive) pages pass `false`. Default true. */
 	enabled?: boolean;
@@ -49,48 +44,20 @@ export interface QueryResult<T> {
 	refetch: () => void;
 }
 
-function remember(key: string, entry: CacheEntry): void {
-	cache.delete(key);
-	cache.set(key, entry);
-	if (cache.size > CACHE_LIMIT) {
-		const oldest = cache.keys().next().value;
-		if (oldest !== undefined) cache.delete(oldest);
-	}
-}
-
-/** Fetch into the cache, sharing one request among concurrent callers of the same key. */
-function load<T>(key: string, fetcher: () => Promise<T>, version: number): Promise<T> {
-	const pending = inflight.get(key);
-	if (pending) return pending as Promise<T>;
-	const promise = fetcher()
-		.then(data => {
-			remember(key, { data, updatedAt: Date.now(), version });
-			return data;
-		})
-		.finally(() => {
-			inflight.delete(key);
-		});
-	inflight.set(key, promise);
-	return promise;
-}
-
 /** Warm the cache for a key the user is likely to open next. No-op if cached for this version. */
 export function prefetchQuery<T>(key: readonly unknown[], fetcher: () => Promise<T>, version: number): void {
 	const keyString = JSON.stringify(key);
-	const entry = cache.get(keyString);
+	const entry = cachedEntry(keyString);
 	if (entry && entry.version >= version) return;
-	load(keyString, fetcher, version).catch(() => {});
+	// Never released: a prefetch runs to completion.
+	loadQuery(keyString, currentLiveVersion(), fetcher).promise.catch(() => {});
 }
 
-export function useQuery<T>(
-	key: readonly unknown[],
-	fetcher: () => Promise<T>,
-	options?: QueryOptions,
-): QueryResult<T> {
+export function useQuery<T>(key: readonly unknown[], fetcher: QueryFetcher<T>, options?: QueryOptions): QueryResult<T> {
 	const keyString = JSON.stringify(key);
 	const enabled = options?.enabled ?? true;
 	const pollMs = options?.pollMs;
-	const { version } = useLive();
+	const version = useLiveVersion(enabled);
 
 	const [, rerender] = useReducer((n: number) => n + 1, 0);
 	const [error, setError] = useState<{ key: string; error: Error } | null>(null);
@@ -100,35 +67,59 @@ export function useQuery<T>(
 	fetcherRef.current = fetcher;
 	const keyRef = useRef(keyString);
 	keyRef.current = keyString;
-	const versionRef = useRef(version);
-	versionRef.current = version;
 	const lastShown = useRef<{ key: string; data: unknown; updatedAt: number } | null>(null);
 	const lastFetchAt = useRef(0);
+	/** The request this query currently waits on. */
+	const waiting = useRef<{ key: string; request: Inflight } | null>(null);
 
 	const run = useCallback((targetKey: string) => {
 		lastFetchAt.current = Date.now();
+		const current = waiting.current;
+		if (current?.key === targetKey && inflightRequest(targetKey) === current.request) return;
+		const shownBefore = cachedEntry(targetKey)?.data;
 		setRefreshing(true);
-		load(targetKey, () => fetcherRef.current(), versionRef.current)
-			.then(() => {
+		const request = loadQuery(targetKey, currentLiveVersion(), fetcherRef.current);
+		waiting.current = { key: targetKey, request };
+		// Join the new request before leaving the old one, so a shared request isn't aborted in between.
+		if (current) releaseQuery(current.key, current.request);
+		request.promise
+			.then(data => {
 				if (keyRef.current !== targetKey) return;
+				// Revalidated to the very same object: nothing on screen changes.
+				if (data === shownBefore) {
+					setError(prev => (prev === null ? prev : null));
+					return;
+				}
 				startTransition(() => {
 					setError(null);
 					rerender();
 				});
 			})
 			.catch((err: unknown) => {
-				if (keyRef.current !== targetKey) return;
+				if (keyRef.current !== targetKey || request.controller.signal.aborted) return;
 				setError({ key: targetKey, error: err instanceof Error ? err : new Error(String(err)) });
 			})
 			.finally(() => {
+				if (waiting.current?.request === request) waiting.current = null;
 				if (keyRef.current === targetKey) setRefreshing(false);
 			});
 	}, []);
 
+	/** Stop waiting so an abandoned multi-MB fetch can be aborted. */
+	const leave = useCallback(() => {
+		const current = waiting.current;
+		waiting.current = null;
+		if (current) releaseQuery(current.key, current.request);
+	}, []);
+
+	// Unmounting, disabling, or switching keys abandons the current request.
+	useEffect(() => leave, [leave]);
+
 	// Fetch on key change / enable / data-version bump when the cache is behind.
 	useEffect(() => {
+		if (!enabled || (waiting.current && waiting.current.key !== keyString)) leave();
 		if (!enabled) return;
-		const entry = cache.get(keyString);
+		const entry = cachedEntry(keyString);
 		if (entry && entry.version >= version) return;
 		const wait = entry ? lastFetchAt.current + LIVE_REFETCH_THROTTLE_MS - Date.now() : 0;
 		if (wait <= 0) {
@@ -137,7 +128,7 @@ export function useQuery<T>(
 		}
 		const timer = setTimeout(() => run(keyString), wait);
 		return () => clearTimeout(timer);
-	}, [keyString, enabled, version, run]);
+	}, [keyString, enabled, version, run, leave]);
 
 	useEffect(() => {
 		if (!enabled || !pollMs) return;
@@ -149,7 +140,7 @@ export function useQuery<T>(
 
 	const refetch = useCallback(() => run(keyRef.current), [run]);
 
-	const entry = cache.get(keyString);
+	const entry = cachedEntry(keyString);
 	if (entry) lastShown.current = { key: keyString, data: entry.data, updatedAt: entry.updatedAt };
 	const shown = lastShown.current;
 	const currentError = error?.key === keyString ? error.error : null;

package/src/client/data/range.ts

@@ -4,7 +4,7 @@
  * formatting, and the contiguous bucket axis charts plot against.
  */
 
-import { format } from "@linxiraos/pi-utils/dates";
+import { getLocale, type MessageKey } from "../i18n";
 import type { TimeRange } from "../types";
 
 const MINUTE_MS = 60 * 1000;
@@ -12,10 +12,10 @@ const HOUR_MS = 60 * MINUTE_MS;
 const DAY_MS = 24 * HOUR_MS;
 
 export interface RangeMeta {
-	/** Short selector label ("24h"). */
-	label: string;
+	/** Short selector label ("24h"); translated so the selector reads in the host language. */
+	labelKey: MessageKey;
 	/** Prose label for subtitles ("the last 24 hours"). */
-	windowLabel: string;
+	windowKey: MessageKey;
 	/** Span covered by the range; `null` for all time. */
 	spanMs: number | null;
 	/** Bucket size of the server's primary time series for this range. */
@@ -23,12 +23,12 @@ export interface RangeMeta {
 }
 
 const RANGE_META: Record<TimeRange, RangeMeta> = {
-	"1h": { label: "1h", windowLabel: "the last hour", spanMs: HOUR_MS, bucketMs: 5 * MINUTE_MS },
-	"24h": { label: "24h", windowLabel: "the last 24 hours", spanMs: DAY_MS, bucketMs: HOUR_MS },
-	"7d": { label: "7d", windowLabel: "the last 7 days", spanMs: 7 * DAY_MS, bucketMs: DAY_MS },
-	"30d": { label: "30d", windowLabel: "the last 30 days", spanMs: 30 * DAY_MS, bucketMs: DAY_MS },
-	"90d": { label: "90d", windowLabel: "the last 90 days", spanMs: 90 * DAY_MS, bucketMs: DAY_MS },
-	all: { label: "All", windowLabel: "all time", spanMs: null, bucketMs: DAY_MS },
+	"1h": { labelKey: "common.range-1h", windowKey: "common.window-1h", spanMs: HOUR_MS, bucketMs: 5 * MINUTE_MS },
+	"24h": { labelKey: "common.range-24h", windowKey: "common.window-24h", spanMs: DAY_MS, bucketMs: HOUR_MS },
+	"7d": { labelKey: "common.range-7d", windowKey: "common.window-7d", spanMs: 7 * DAY_MS, bucketMs: DAY_MS },
+	"30d": { labelKey: "common.range-30d", windowKey: "common.window-30d", spanMs: 30 * DAY_MS, bucketMs: DAY_MS },
+	"90d": { labelKey: "common.range-90d", windowKey: "common.window-90d", spanMs: 90 * DAY_MS, bucketMs: DAY_MS },
+	all: { labelKey: "common.range-all", windowKey: "common.window-all", spanMs: null, bucketMs: DAY_MS },
 };
 
 const MAX_BUCKETS = 1500;
@@ -40,16 +40,36 @@ export function rangeMeta(range: TimeRange): RangeMeta {
 	return RANGE_META[range];
 }
 
+/** Layouts shared by the axis and its tooltips. */
+const HOUR_OPTIONS = { hour: "2-digit", minute: "2-digit", hourCycle: "h23" } as const;
+const DAY_OPTIONS = { month: "short", day: "numeric" } as const;
+
+/** One formatter per locale+layout: charts re-render on every tick, so this must not allocate per call. */
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(layout: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+	const locale = getLocale();
+	const key = `${locale}:${layout}`;
+	let cached = formatterCache.get(key);
+	if (!cached) {
+		cached = new Intl.DateTimeFormat(locale, options);
+		formatterCache.set(key, cached);
+	}
+	return cached;
+}
+
 /** Tick/tooltip label for a bucket start, precise enough for the bucket size. */
 export function formatBucket(timestamp: number, bucketMs: number): string {
-	if (bucketMs < DAY_MS) return format(new Date(timestamp), bucketMs < HOUR_MS ? "HH:mm" : "MMM d HH:mm");
-	return format(new Date(timestamp), "MMM d");
+	if (bucketMs < HOUR_MS) return formatter("hm", HOUR_OPTIONS).format(timestamp);
+	if (bucketMs < DAY_MS) return formatter("mdhm", { ...DAY_OPTIONS, ...HOUR_OPTIONS }).format(timestamp);
+	return formatter("md", DAY_OPTIONS).format(timestamp);
 }
 
 /** Compact axis tick for a bucket start. */
 export function formatTick(timestamp: number, bucketMs: number): string {
-	if (bucketMs < DAY_MS) return format(new Date(timestamp), "HH:mm");
-	return format(new Date(timestamp), "MMM d");
+	return bucketMs < DAY_MS
+		? formatter("hm", HOUR_OPTIONS).format(timestamp)
+		: formatter("md", DAY_OPTIONS).format(timestamp);
 }
 
 /**

package/src/client/data/series.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ChartSeries } from "../charts/types";
+import { t } from "../i18n";
 import { OTHER_COLOR, SERIES_COLORS } from "./colors";
 
 /** Sum `value(point)` into a dense array aligned to `buckets`. Out-of-axis points are dropped. */
@@ -73,7 +74,12 @@ export function pivotSeries<P extends { timestamp: number }>(
 	if (tail.length > 0) {
 		const other = Array.from({ length: opts.buckets.length }, () => 0);
 		for (const entry of tail) for (let i = 0; i < other.length; i++) other[i] += entry.values[i];
-		series.push({ key: "__other__", label: `Other (${tail.length})`, color: OTHER_COLOR, values: other });
+		series.push({
+			key: "__other__",
+			label: t("common.other-n", { count: tail.length }),
+			color: OTHER_COLOR,
+			values: other,
+		});
 	}
 	return series;
 }

package/src/client/i18n/format.ts

@@ -0,0 +1,28 @@
+import type { MessagesByLocale, StatsLocale, TranslationParams } from "./types";
+
+/** Substitute `{name}` placeholders; unknown names are left verbatim so a bug is visible, not silent. */
+export function interpolateMessage(message: string, params: TranslationParams = {}): string {
+	return message.replace(/\{([\w.-]+)\}/g, (token, name: string) => {
+		const value = params[name];
+		return value === undefined ? token : String(value);
+	});
+}
+
+/**
+ * Resolve a message for `locale`, falling back to English and finally to the
+ * key itself. The key fallback is deliberate: a renamed key renders its slug
+ * rather than blanking a card, so a missed rename is visible but not fatal.
+ */
+export function translateMessage(
+	locale: StatsLocale,
+	key: string,
+	messages: MessagesByLocale,
+	params: TranslationParams = {},
+): string {
+	const message = messages[locale]?.[key] ?? messages.en?.[key];
+	if (message === undefined) {
+		if (process.env.NODE_ENV !== "production") console.warn(`[stats.i18n] missing translation: ${key}`);
+		return key;
+	}
+	return interpolateMessage(message, params);
+}

package/src/client/i18n/index.ts

@@ -0,0 +1,53 @@
+import { resolveBrowserLocale, resolveLocaleTag } from "../../locale";
+import { translateMessage } from "./format";
+import { enLocale, type MessageKey } from "./messages/en";
+import { zhCNLocale } from "./messages/zh-CN";
+import type { MessagesByLocale, StatsLocale, TranslationParams } from "./types";
+
+/** The inline global the server stamps into `<head>` (see `server.ts`); read through `globalThis` so this module compiles without a DOM lib. */
+function injectedLocale(): string | undefined {
+	return (globalThis as { __ZETA_STATS_LOCALE__?: string }).__ZETA_STATS_LOCALE__;
+}
+
+const messages: MessagesByLocale = { en: enLocale.messages, "zh-CN": zhCNLocale.messages };
+
+let activeLocale: StatsLocale = "en";
+
+// Resolve once at module load. Every `t()` caller imports this module first, so
+// the host language the server injected into `<head>` (or the browser's own
+// preference) is already in effect by the time a component module is evaluated
+// — including module-level label tables such as the range selector's.
+resolveInitialLocale();
+
+/** The locale the dashboard renders in. Fixed at boot; there is no in-page switcher. */
+export function getLocale(): StatsLocale {
+	return activeLocale;
+}
+
+/** Install a locale by tag (`zh`, `zh-CN`, `zh-Hans`; anything else is English). */
+export function setLocale(tag: string | undefined | null): StatsLocale {
+	activeLocale = resolveLocaleTag(tag);
+	return activeLocale;
+}
+
+/**
+ * The locale to boot with: the host's language when `zeta-c stats` injected it,
+ * then the browser's own preference, then English.
+ */
+export function resolveInitialLocale(): StatsLocale {
+	const injected = injectedLocale();
+	if (injected) return setLocale(injected);
+	if (typeof navigator === "undefined") return "en";
+	return setLocale(resolveBrowserLocale(navigator.languages));
+}
+
+/**
+ * Translate `key` in the active locale; `{name}` placeholders substitute from
+ * `params`. The key type is the English catalogue, so an unknown key is a
+ * compile error rather than a silently blank card.
+ */
+export function t(key: MessageKey, params?: TranslationParams): string {
+	return translateMessage(activeLocale, key, messages, params);
+}
+
+export type { MessageKey, StatsLocale, TranslationParams };

package/src/client/i18n/messages/charts.ts

@@ -0,0 +1,8 @@
+/**
+ * Charts copy. Keys are slugs (`charts.<name>`); the English string is the
+ * source of truth and `zh-CN` overrides it.
+ */
+export const charts = {
+	en: {},
+	"zh-CN": {},
+} as const;