@aiquants/spreadsheet 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/spreadsheet",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
   "sideEffects": [
     "**/*.css"
@@ -34,12 +34,12 @@
     "LICENSE.md"
   ],
   "peerDependencies": {
-    "@aiquants/virtualscroll": "^3.6.1",
+    "@aiquants/virtualscroll": "^3.7.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@aiquants/virtualscroll": "3.6.1",
+    "@aiquants/virtualscroll": "3.7.0",
     "@playwright/test": "^1.59.1",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/jest-dom": "^6.9.1",

package/src/Spreadsheet.tsx

@@ -27,6 +27,10 @@
  * clipboard / keyboard (executeCommandRef / openPopoverRef / hideNoteTipRef / pasteRef /
  * pendingPasteOptionsRef / popover anchors).
  *
+ * UI chrome locale: the `locale` prop is resolved once (`resolveVirtualScrollLocale` — undefined ⇒
+ * "en", unknown ⇒ RangeError at render) and drives the label catalog, the built-in validation
+ * messages and — through a value-stable engine subset — the grid scrollbars.
+ *
  * v0.8 (計画 §4.2.13 — フック順は設計 v5): 軸モデル → viewStore → ズーム → オートスクローラー
  * 6 台 (6 台目は参照ドラッグ用) → 選択エンジン → ヘッダー機械 ×2 → ヘッダーリサイズ → fill →
  * 参照ドラッグ (usePointDrag) → 合成ドラッグ面 (isDraggingAny / abortDragAny / "point" 込みの
@@ -37,9 +41,13 @@
  * ポインティングの ref 辺 (editor → engine / ヘッダー / 参照ドラッグ / body / コーナー / ズーム死空間)、
  * コマンド / ポップオーバー / クリップボード / キーボード間の ref 辺 (executeCommandRef /
  * openPopoverRef / hideNoteTipRef / pasteRef / pendingPasteOptionsRef / ポップオーバーアンカー) を所有する。
+ *
+ * UI クロームロケール: `locale` prop を 1 回だけ解決し (`resolveVirtualScrollLocale` — undefined は
+ * "en"、未知は render 中 RangeError)、ラベルカタログ・組み込み検証メッセージ・値安定なエンジン部分集合
+ * 経由のグリッドスクロールバーを駆動する。
  */
 
-import type { ScrollBarTapCircleOptions, VirtualGridHandle, VirtualGridRange } from "@aiquants/virtualscroll"
+import { resolveVirtualScrollLocale, type ScrollBarTapCircleOptions, VIRTUAL_SCROLL_LABEL_KEYS, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels } from "@aiquants/virtualscroll"
 import type { ProfilerOnRenderCallback } from "react"
 import { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react"
 import type { ClipChannel } from "./clipboard/clipPayload.ts"
@@ -67,7 +75,7 @@ import { type CellEdit, type EditContext, type EditRejection, type EditSource, i
 import { type DataValidationRule, type ValidationVerdict, validateCellText } from "./model/dataValidation.ts"
 import type { ReferenceAxis } from "./model/formulaRefs.ts"
 import { colToViewportX, rowToViewportY } from "./model/frozenPartition.ts"
-import { resolveLabels, type SpreadsheetLabelOverrides } from "./model/labels.ts"
+import { pickEngineLabels, resolveLabels, type SpreadsheetLabelOverrides, type SpreadsheetLocale } from "./model/labels.ts"
 import { createViewStore, type ViewStore } from "./model/viewStore.ts"
 import { DEFAULT_HIGHLIGHT_COLORS, type DragFrameMode, type HighlightColors, type HighlightState, type ResizeGuide, SelectionOverlay } from "./overlay/SelectionOverlay.tsx"
 import { useFillHandle } from "./overlay/useFillHandle.ts"
@@ -437,14 +445,30 @@ export type SpreadsheetProps = {
      * コマンドの AT 通知 (opt-in、v0.8 §1.9)。`state` はトグル後状態 (非トグルは null)。live region へ。
      */
     formatCommandAnnouncement?: (ctx: { command: SpreadsheetCommand; state: boolean | null }) => string
+    /**
+     * UI chrome language ("en" | "ja"; default "en"): selects the label catalog, the built-in
+     * data-validation messages, and is forwarded to the grid scrollbars (arrow labels,
+     * scroll-to-edge pills, "No items"). An unsupported value throws a RangeError during render —
+     * there is no language negotiation: hosts map `navigator.language` themselves. Unrelated to
+     * `formats.locale`, which is the BCP-47 value-formatting locale ("ja-JP" is NOT a valid value
+     * here).
+     * UI クローム言語 ("en" | "ja"、既定 "en"): ラベルカタログと組み込みデータ検証メッセージを選び、
+     * グリッドのスクロールバー (矢印ラベル・端スクロールピル・"No items") へ素通し。非対応値は render 中
+     * RangeError — 言語ネゴシエーションなし (`navigator.language` の写像はホスト側)。値書式の BCP-47
+     * ロケールである `formats.locale` とは無関係 ("ja-JP" はここでは不正値)。
+     */
+    locale?: SpreadsheetLocale
     /**
      * UI label vocabulary (v0.8 §1.6) — folds the former `sinkAriaLabel` / `rootAriaLabel` props
-     * (clean cut-over). An omitted or explicitly `undefined` key keeps the English default. The
-     * resolved `sinkAriaLabel` MUST mention "Escape" (WCAG 2.1.2 escape advisement, §10-4) — a
-     * RangeError is thrown during render otherwise.
+     * (clean cut-over). 28 keys = the 7 engine chrome keys (scrollUp / scrollDown / scrollLeft /
+     * scrollRight / scrollToTop / scrollToBottom / noItems) + 21 own keys. An omitted prop or an
+     * explicitly `undefined` key keeps the value of the `locale` catalog. An unknown key or an
+     * empty / blank value throws a RangeError during render, and the resolved `sinkAriaLabel` MUST
+     * mention "Escape" (WCAG 2.1.2 escape advisement, §10-4).
      * UI ラベル語彙 (v0.8 §1.6) — 旧 sinkAriaLabel / rootAriaLabel prop を畳込み (クリーンカットオーバー)。
-     * 省略 / 明示 undefined は英語既定。解決後の sinkAriaLabel は "Escape" を含むこと (違反は render 中
-     * RangeError — §10-4)。
+     * 28 キー = エンジンクローム 7 キー (scrollUp / scrollDown / scrollLeft / scrollRight / scrollToTop /
+     * scrollToBottom / noItems) + 固有 21 キー。prop 省略 / 明示 undefined のキーは `locale` のカタログ値。
+     * 未知キー・空 / 空白値は render 中 RangeError、解決後の sinkAriaLabel は "Escape" を含むこと (§10-4)。
      */
     labels?: SpreadsheetLabelOverrides
     /**
@@ -505,7 +529,7 @@ export type SpreadsheetProps = {
     onClipChange?: (clip: ClipInfo | null) => void
     /** Hyperlink navigation seam (Alt+Enter, the link popover's Open button, and Ctrl / Meta+click on a link cell — spec 08 §11 D-53) — undeclared ⇒ no navigation, no Open button, no pointer gesture. / ハイパーリンク遷移シーム (Alt+Enter / Open ボタン / リンクセルへの Ctrl / Meta+クリック — 分冊 08 §11 D-53)。未宣言 = 遷移なし・Open ボタンなし・ポインタジェスチャなし。 */
     onHyperlinkOpen?: (url: string, cell: CellCoord) => void
-    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。 */
+    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. `message` is `rule.errorMessage` when declared, otherwise the built-in message in the active `locale`. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。`message` は `rule.errorMessage` 宣言時はそれ、未宣言なら現在の `locale` の組み込みメッセージ。 */
     onValidationRejected?: (ctx: { cell: CellCoord; rule: DataValidationRule; text: string; message: string }) => void
     /** Ctrl+Alt+V request with the active cell's viewport rect (visual px, keyboard-origin shape of onCellContextMenu); undeclared ⇒ `paste({ mode: "formats" })`. / Ctrl+Alt+V の要求通知 (未宣言なら書式のみ貼り付け)。 */
     onPasteSpecialRequest?: (origin: { kind: "keyboard"; cellRect: { top: number; left: number; width: number; height: number } }) => void
@@ -715,6 +739,28 @@ const requirePasteSheet = (sheet: PasteSheet | undefined): PasteSheet => {
     return sheet
 }
 
+/**
+ * Keeps the previous engine label object while all 7 strings are value-equal, so the object handed
+ * to the memoized GridBody changes identity only when a string changes (a host passing an inline
+ * `labels={{…}}` must not re-render the grid body on every shell render).
+ * 7 文字列がすべて値等価の間は前回のエンジンラベル object を保持 — memo 化された GridBody へ渡す
+ * object の identity は文字列が変わった時だけ変わる (インライン `labels={{…}}` のホストでも shell
+ * 再レンダー毎に本体を再描画させない)。
+ *
+ * @param next - The engine labels resolved in this render / 今回の render で解決したエンジンラベル
+ * @returns `next`, or the previous object when every key is value-equal / `next`、全キー値等価なら前回の object
+ */
+const useValueStableScrollLabels = (next: VirtualScrollLabels): VirtualScrollLabels => {
+    const stableRef = useRef<VirtualScrollLabels | null>(null)
+    const previous = stableRef.current
+    if (previous !== null && VIRTUAL_SCROLL_LABEL_KEYS.every((key) => previous[key] === next[key])) {
+        return previous
+    }
+    // レンダー時代入: 値等価比較の基準だけを保持し、副作用は持たない (破棄された render でも比較結果は同じ)
+    stableRef.current = next
+    return next
+}
+
 /** Initial A1 selection. / 初期 A1 選択。 */
 const INITIAL_SELECTION: SelectionState = {
     ranges: [makeRange({ row: 0, col: 0 }, { row: 0, col: 0 })],
@@ -757,6 +803,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         formatCellAnnouncement,
         formatSelectionAnnouncement,
         formatCommandAnnouncement,
+        locale,
         labels,
         shortcuts,
         colors,
@@ -797,8 +844,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     const viewStore = viewStoreRef.current
 
     // ---- prop 時検証 (v0.8 §4.2.13 — clampZoom と同じく render 中に RangeError を投げる) ----
+    // 非対応ロケールはここで render 中 RangeError — 以降の検証メッセージ / GridBody は解決済み値だけを受ける
+    const uiLocale = resolveVirtualScrollLocale(locale)
     // ラベルの畳込み: resolveLabels が Escape 告知 (§10-4) を検証する (RC22)
-    const resolvedLabels = useMemo(() => resolveLabels(labels), [labels])
+    const resolvedLabels = useMemo(() => resolveLabels(locale, labels), [locale, labels])
+    // GridBody は memo 境界 — インライン labels で毎回新 object になっても 7 文字列が同じなら identity を保つ
+    const scrollLabels = useValueStableScrollLabels(pickEngineLabels(resolvedLabels))
     // コマンド表: validateShortcuts の 5 条件 (+ 未知キー) は consumer の設定誤り — render 中に表面化
     const commandTable = useMemo(() => validateShortcuts(shortcuts), [shortcuts])
     // カスタム色スロット (各軸ちょうど 5 本の #rrggbb)
@@ -1897,10 +1948,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
      * The validation gate (v0.8 §4.2.6 / 分冊 08 §4.2), shared by the editor's changed commit and
      * the editing-column `fillSelection` (which runs it per target cell): no rule / non-strict ⇒
      * ok (the cell keeps its invalid mark); only a strict rejection stops the commit and reports
-     * through `onValidationRejected` + the `message` popover (`rejected`).
+     * through `onValidationRejected` + the `message` popover (`rejected`). The verdict message is
+     * `rule.errorMessage` when declared, otherwise the built-in message in the resolved UI locale.
      * 検証ゲート (v0.8 §4.2.6 / 分冊 08 §4.2) — エディタの変更ある確定と編集列 fillSelection (対象セル毎)
      * が共有。規則なし / 非 strict は受理 (セルは不正表示のまま)、strict の拒否だけが commit を止めて
-     * onValidationRejected + message ポップオーバー (rejected) を出す。
+     * onValidationRejected + message ポップオーバー (rejected) を出す。判定メッセージは `rule.errorMessage`
+     * 宣言時はそれ、未宣言なら解決済み UI ロケールの組み込みメッセージ。
      */
     const validateCommit = useCallback(
         (cell: CellCoord, text: string): ValidationVerdict => {
@@ -1909,7 +1962,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 return OK_VERDICT
             }
             const evaluateFormula = adapter.evaluateFormula
-            const verdict = validateCellText(rule, text, evaluateFormula === undefined ? undefined : (formula) => evaluateFormula(formula, cell))
+            const verdict = validateCellText(rule, text, uiLocale, evaluateFormula === undefined ? undefined : (formula) => evaluateFormula(formula, cell))
             if (verdict.ok || rule.strict !== true) {
                 return OK_VERDICT
             }
@@ -1920,7 +1973,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             }
             return verdict
         },
-        [adapter, onValidationRejected],
+        [adapter, onValidationRejected, uiLocale],
     )
     const editor = useCellEditor({
         enabled: !isEmpty,
@@ -2777,6 +2830,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         cfIndexRef={cfIndexRef}
                         cfMemoRef={cfMemoRef}
                         isPointing={isPointing}
+                        locale={uiLocale}
+                        scrollLabels={scrollLabels}
                     />
                     <SelectionOverlay
                         rowAxis={rowAxis}

package/src/grid/GridBody.tsx

@@ -28,6 +28,10 @@
  * helper (ADR-31 — no package CSS; capability absent ⇒ O(1) false ⇒ keys absent ⇒ the DOM
  * stays byte-identical).
  *
+ * UI chrome locale: the resolved `locale` and the value-stable engine subset `scrollLabels` are
+ * forwarded to VirtualGrid, which localizes the embedded vertical bar, the horizontal bar and the
+ * degenerate-band "No items" — no lang attribute, no new data-* hook.
+ *
  * グリッド本体。VirtualGrid 結線 (両軸) とセルレンダラーを所有する。v0.4 から横軸は VirtualGrid
  * の所有 (量子化列アンカー + 残差 transform + 横バー) — v0.3 の列スタック (useColumnWindow /
  * --aqsp-hx CSS 変数 / 軸原点絶対 left / 自前 HScrollBar) は設計計画 §7-1 に従い削除。
@@ -50,9 +54,12 @@
  * v0.10 読み取り専用セル (計画 §6.5、S1): `getCellProps` が塗られた読み取り専用セルへ
  * `aria-readonly="true"` + `data-aqsp-readonly=""` を `isReadOnlyCell` ヘルパ経由で条件スタンプ
  * する (ADR-31 — パッケージ CSS なし。能力未宣言 = O(1) false = キー不在 = DOM バイト同一)。
+ *
+ * UI クロームロケール: 解決済み `locale` と値安定なエンジン部分集合 `scrollLabels` を VirtualGrid へ
+ * 素通しし、埋込み縦バー・横バー・退化帯の "No items" を現地化する (lang 属性・新規 data-* フックなし)。
  */
 
-import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange } from "@aiquants/virtualscroll"
+import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels } from "@aiquants/virtualscroll"
 import { type HTMLAttributes, memo, type ProfilerOnRenderCallback, type ReactNode, type RefObject, useCallback, useMemo, useRef, useSyncExternalStore } from "react"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
 import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
@@ -61,6 +68,7 @@ import { type CellPaint, resolveCellPaint } from "../model/cellPaint.ts"
 import { type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "../model/conditionalFormat.ts"
 import { isReadOnlyCell, lazyCellText, resolveCellAlign, resolveCellAttributes, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { isVisiblyInvalid } from "../model/dataValidation.ts"
+import type { SpreadsheetLocale } from "../model/labels.ts"
 import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
 import { CellView, type RenderCellContext } from "./CellView.tsx"
 
@@ -338,6 +346,23 @@ type GridBodyProps = {
     background?: ReactNode
     /** Rendering-truncation signal (engine `onRenderTruncated` pass-through — trailing columns dropped under the cell cap). / 描画打切り通知 (エンジン `onRenderTruncated` の素通し — セル上限下の末尾列脱落)。 */
     onRenderTruncated?: (info: { renderedCells: number; droppedCols: number }) => void
+    /**
+     * The RESOLVED UI chrome locale (never undefined — the root resolves the `locale` prop through
+     * `resolveVirtualScrollLocale`), forwarded to VirtualGrid's `locale`.
+     * 解決済みの UI クロームロケール (undefined にならない — root が `locale` prop を
+     * `resolveVirtualScrollLocale` で解決)。VirtualGrid の `locale` へ素通し。
+     */
+    locale: SpreadsheetLocale
+    /**
+     * The resolved engine chrome strings (the 7 VirtualScrollLabels keys: scroll arrows,
+     * scroll-to-edge pills, "No items"), forwarded to VirtualGrid's `labels`. MUST be value-stable:
+     * its identity may change only when one of the 7 strings changes, otherwise every shell render
+     * pierces the memo boundary.
+     * 解決済みエンジンクローム文言 (VirtualScrollLabels の 7 キー: スクロール矢印・端スクロールピル・
+     * "No items")。VirtualGrid の `labels` へ素通し。値安定であること (7 文字列のどれかが変わった時だけ
+     * identity が変わる — さもなくば shell 再レンダー毎に memo 境界を貫通)。
+     */
+    scrollLabels: VirtualScrollLabels
 }
 
 /**
@@ -373,6 +398,8 @@ const GridBodyInner = ({
     overscanCols,
     background,
     onRenderTruncated,
+    locale,
+    scrollLabels,
 }: GridBodyProps): ReactNode => {
     const internalBodyRef = useRef<HTMLDivElement | null>(null)
     // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -554,6 +581,8 @@ const GridBodyInner = ({
                 background={background}
                 onRenderTruncated={onRenderTruncated}
                 __maxRenderedCells={__maxRenderedCells}
+                locale={locale}
+                labels={scrollLabels}
                 callbackThrottleMs={0}
                 onScroll={onScroll}
                 onRangeChange={onRangeChange}

package/src/index.ts

@@ -110,7 +110,7 @@ export {
     validateCellText,
 } from "./model/dataValidation.ts"
 export { fromR1C1, shiftFormula, toR1C1 } from "./model/formulaRefs.ts"
-export { DEFAULT_LABELS, resolveLabel, type SpreadsheetLabelOverrides, type SpreadsheetLabels } from "./model/labels.ts"
+export { resolveLabel, resolveLabels, SPREADSHEET_LABEL_CATALOGS, type SpreadsheetLabelOverrides, type SpreadsheetLabels, type SpreadsheetLocale } from "./model/labels.ts"
 export { DEFAULT_HIGHLIGHT_COLORS, type HighlightColors, type HighlightState } from "./overlay/SelectionOverlay.tsx"
 // 既定ポップオーバー 6 種 — renderPopover の部品 (kind 別に差し替え、残りは既定を組み合わせる)
 export { CommentPopover, type CommentPopoverProps } from "./popover/CommentPopover.tsx"

package/src/model/dataValidation.ts

@@ -26,7 +26,8 @@
  * - INTERNED list Sets per rule object (WeakMap identity), so the paint-time `list` check is O(1)
  *   even for a 10k-item list; a fresh rule object interns a fresh Set.
  * - MESSAGE resolution: `errorMessage` when the consumer set it (an empty string is honoured as
- *   is), else a built-in English summary of the rule.
+ *   is), else the built-in summary of the rule in the caller's REQUIRED `locale`
+ *   (validationMessages.ts); an unsupported locale throws RangeError before any verdict.
  * - `custom` needs the caller's `evaluate`; without it the rule is not evaluated (verdict ok), and
  *   truth = `true` or a finite non-zero number (the conditionalFormat customFormula convention).
  * - Matching is exact (case-sensitive, untrimmed) for `list` / `text` / `checkbox`; textLength
@@ -43,11 +44,15 @@
  * タプル比較 (between は両端含み)、不完全な規則 (解釈不能な境界・between の b 欠落・needle 欠落) は
  * 不活性 = 全受理 (書きかけの規則でセルを閉じ込めない、境界の入替もしない)、語彙外の type / op は
  * consumer バグとして text に依らず RangeError、list の Set は規則 object 毎に WeakMap intern、
- * メッセージは errorMessage (空文字も尊重) が無ければ組込みの英語要約、custom は evaluate 無しなら
+ * メッセージは errorMessage (空文字も尊重) が無ければ呼び手必須の locale による組込み要約
+ * (validationMessages.ts — 非対応ロケールは判定前に RangeError)、custom は evaluate 無しなら
  * 未評価 (ok)・真 = true か有限非 0 数、照合は完全一致 (大文字小文字区別・trim 無し)、textLength は
  * コードポイント数、isEmail は WHATWG 文法 + ドット付きドメイン必須、isUrl は WHATWG 絶対 http(s) URL。
  */
 
+import { describeLabelValue, type SpreadsheetLocale } from "./labels.ts"
+import { VALIDATION_MESSAGE_CATALOGS, type ValidationMessageCatalog } from "./validationMessages.ts"
+
 /** Ordered comparison vocabulary shared by number / textLength / date rules; between / notBetween include both bounds. / number / textLength / date 規則が共有する比較語彙。between / notBetween は両端含み。 */
 export type ValidationCompareOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "notBetween"
 
@@ -127,15 +132,6 @@ type Ordering = -1 | 0 | 1
 /** Resolved bounds of an ordered rule; `b` is null when the op does not use it. / 順序規則の解決済み境界。op が使わないとき b は null。 */
 type Bounds<T> = { a: T; b: T | null }
 
-/** Rule-family wording for the four ordered ops (the other four are shared). / 順序 4 op の規則族別の言い回し (残る 4 つは共通)。 */
-type OrderWords = { readonly gt: string; readonly gte: string; readonly lt: string; readonly lte: string }
-
-/** Wording for number / textLength messages. / number / textLength メッセージの言い回し。 */
-const NUMERIC_WORDS: OrderWords = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
-
-/** Wording for date messages. / date メッセージの言い回し。 */
-const DATE_WORDS: OrderWords = { gt: "after", gte: "on or after", lt: "before", lte: "on or before" }
-
 /**
  * Parses a strict decimal string into its exact normalised form: trims, applies the
  * cellFormat.ts grammar (hex / grouping / empty rejected, exponent overflow to ±Infinity
@@ -367,9 +363,16 @@ const checkboxStrings = (rule: CheckboxValidationRule): { checked: string; unche
 
 /**
  * Rejects a rule outside the vocabulary (unknown `type`, or an unknown `op` on number /
- * textLength / date / text) with RangeError — a consumer bug surfaces regardless of the text.
+ * textLength / date / text) with RangeError — a consumer bug surfaces regardless of the text. The
+ * rejected value is described by `describeLabelValue`, so a Symbol / null-prototype `type` or `op`
+ * still yields the RangeError (never a TypeError from the message itself).
  * 語彙外の規則 (未知 type、number / textLength / date / text の未知 op) を RangeError で拒否 —
- * consumer バグは text に依らず表面化。
+ * consumer バグは text に依らず表面化。拒否値は `describeLabelValue` で説明するため、Symbol / null
+ * プロトタイプの type や op でもメッセージ組立て自体が TypeError を投げず RangeError のまま。
+ *
+ * @param rule - The rule to check / 検査する規則
+ * @returns Nothing; returns normally for an in-vocabulary rule / なし (語彙内の規則なら正常終了)
+ * @throws {RangeError} When the rule's `type` / `op` is outside the vocabulary / 規則の type / op が語彙外の場合
  */
 const assertRuleShape = (rule: DataValidationRule): void => {
     switch (rule.type) {
@@ -381,16 +384,16 @@ const assertRuleShape = (rule: DataValidationRule): void => {
         case "textLength":
         case "date":
             if (!COMPARE_OPS.has(rule.op)) {
-                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "${rule.type}"`)
+                throw new RangeError(`[spreadsheet] unknown data-validation op ${describeLabelValue(rule.op)} for type "${rule.type}"`)
             }
             return
         case "text":
             if (!TEXT_OPS.has(rule.op)) {
-                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "text"`)
+                throw new RangeError(`[spreadsheet] unknown data-validation op ${describeLabelValue(rule.op)} for type "text"`)
             }
             return
         default:
-            throw new RangeError(`[spreadsheet] unknown data-validation rule type "${String((rule as { type: unknown }).type)}"`)
+            throw new RangeError(`[spreadsheet] unknown data-validation rule type ${describeLabelValue((rule as { type: unknown }).type)}`)
     }
 }
 
@@ -427,68 +430,61 @@ const accepts = (rule: DataValidationRule, text: string, evaluate: ValidationEva
     return text === "" || ruleHolds(rule, text, evaluate)
 }
 
-/** Phrase for an ordered op with the family wording: "greater than 5", "between 1 and 9", ... / 順序 op の言い回し (規則族の語彙付き)。 */
-const comparePhrase = (op: ValidationCompareOp, a: string, b: string | undefined, words: OrderWords): string => {
-    switch (op) {
-        case "gt":
-        case "gte":
-        case "lt":
-        case "lte":
-            return `${words[op]} ${a}`
-        case "eq":
-            return `equal to ${a}`
-        case "neq":
-            return `not equal to ${a}`
-        case "between":
-            return `between ${a} and ${b}`
-        default:
-            // 残る順序 op は notBetween
-            return `not between ${a} and ${b}`
-    }
-}
-
 /** Trims an optional bound string for display. / 表示用に任意の境界文字列を trim。 */
 const trimBound = (bound: string | undefined): string | undefined => (bound === undefined ? undefined : bound.trim())
 
-/** Built-in English summary of a rule, used when the consumer set no `errorMessage`. / consumer が errorMessage を置かないときの組込み英語要約。 */
-const defaultMessage = (rule: DataValidationRule): string => {
+/**
+ * Built-in summary of a rule in one locale's catalog, used when the consumer set no
+ * `errorMessage`. The bounds are normalised here (number / date bounds trimmed, textLength bounds
+ * stringified, checkbox strings defaulted) so every locale's template sees the same values.
+ * consumer が errorMessage を置かないときの、1 ロケールのカタログによる規則の組込み要約。境界の正規化
+ * (number / date は trim、textLength は文字列化、checkbox は既定適用) をここで行い、全ロケールの
+ * テンプレートが同じ値を受け取る。
+ *
+ * @param rule - The shape-checked rule that rejected the text / text を拒否した形検査済みの規則
+ * @param catalog - The message catalog of the verdict's locale / 判定ロケールのメッセージカタログ
+ * @returns The built-in message / 組込みメッセージ
+ */
+const messageOf = (rule: DataValidationRule, catalog: ValidationMessageCatalog): string => {
     switch (rule.type) {
         case "list":
-            return "Value must be one of the list items."
+            return catalog.list
         case "number":
-            return `Value must be a number ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), NUMERIC_WORDS)}.`
+            return catalog.number[rule.op](rule.a.trim(), trimBound(rule.b))
         case "textLength":
-            return `Text length must be ${comparePhrase(rule.op, String(rule.a), rule.b === undefined ? undefined : String(rule.b), NUMERIC_WORDS)}.`
+            return catalog.textLength[rule.op](String(rule.a), rule.b === undefined ? undefined : String(rule.b))
         case "date":
-            return `Value must be a date ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), DATE_WORDS)}.`
+            return catalog.date[rule.op](rule.a.trim(), trimBound(rule.b))
         case "text":
-            return textMessage(rule)
+            return textMessageOf(rule, catalog.text)
         case "checkbox": {
             const strings = checkboxStrings(rule)
-            return `Value must be "${strings.checked}" or "${strings.unchecked}".`
+            return catalog.checkbox(strings.checked, strings.unchecked)
         }
         default:
             // 残る規則種別は custom
-            return `Value does not satisfy the formula ${rule.formula}.`
+            return catalog.custom(rule.formula)
     }
 }
 
-/** Built-in summary of a text rule. / text 規則の組込み要約。 */
-const textMessage = (rule: TextValidationRule): string => {
+/**
+ * Built-in summary of a text rule from a catalog's `text` templates (needle ops embed `value`; the
+ * shape checks are fixed sentences).
+ * カタログの text テンプレートによる text 規則の組込み要約 (needle 系は value を埋め込み、形式検査は固定文)。
+ *
+ * @param rule - The shape-checked text rule / 形検査済みの text 規則
+ * @param templates - The `text` templates of the verdict's locale / 判定ロケールの text テンプレート
+ * @returns The built-in message / 組込みメッセージ
+ */
+const textMessageOf = (rule: TextValidationRule, templates: ValidationMessageCatalog["text"]): string => {
     switch (rule.op) {
-        case "contains":
-            return `Value must contain "${rule.value}".`
-        case "notContains":
-            return `Value must not contain "${rule.value}".`
-        case "startsWith":
-            return `Value must start with "${rule.value}".`
-        case "endsWith":
-            return `Value must end with "${rule.value}".`
         case "isEmail":
-            return "Value must be a valid email address."
+            return templates.isEmail
+        case "isUrl":
+            return templates.isUrl
         default:
-            // 残る text op は isUrl
-            return "Value must be a valid URL."
+            // needle 系は value 欠落なら不活性で拒否に至らないため、ここへ来るとき value は常にある
+            return templates[rule.op](rule.value as string)
     }
 }
 
@@ -513,20 +509,41 @@ export const listValuesOf = (rule: ListValidationRule): ReadonlySet<string> => {
 }
 
 /**
- * Validates committed text against a rule. Blank always passes; `custom` is evaluated only when
- * the caller passes `evaluate` (commit time — paint omits it); an incomplete rule (unparseable
- * bound, missing `b` / `value`) is inert; a rule outside the vocabulary throws RangeError.
- * Message = `rule.errorMessage` when set, else a built-in English summary of the rule.
- * 確定テキストの規則検証。空文字は常に合格、custom は呼び手が evaluate を渡すとき (確定時 — 描画は
- * 渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は不活性、語彙外の規則は
- * RangeError。メッセージは errorMessage があればそれ、無ければ組込みの英語要約。
+ * Validates committed text against a rule. The locale is checked FIRST (before the rule and the
+ * text), so an unsupported locale fails fast even for a passing text — this pure function has no
+ * hidden default locale. Blank always passes; `custom` is evaluated only when the caller passes
+ * `evaluate` (commit time — paint omits it); an incomplete rule (unparseable bound, missing `b` /
+ * `value`) is inert; a rule outside the vocabulary throws RangeError. Message = `rule.errorMessage`
+ * when set (the empty string included), else the built-in summary in the given locale.
+ * 確定テキストの規則検証。ロケールを最初に (規則と text より前に) 検査するため、非対応ロケールは
+ * 合格する text でも fail-fast (純関数に隠れた既定ロケールは無い)。空文字は常に合格、custom は呼び手が
+ * evaluate を渡すとき (確定時 — 描画は渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は
+ * 不活性、語彙外の規則は RangeError。メッセージは errorMessage があればそれ (空文字も含む)、無ければ
+ * 指定ロケールの組込み要約。
+ *
+ * @param rule - The cell's data-validation rule / セルのデータ検証規則
+ * @param text - The committed text / 確定テキスト
+ * @param locale - The UI chrome locale of the built-in message ("en" | "ja"; required) / 組込みメッセージの UI クロームロケール ("en" | "ja"、必須)
+ * @param evaluate - The consumer's formula evaluator for `custom` rules (omit to leave them unevaluated) / custom 規則用の consumer の数式評価器 (省略で未評価)
+ * @returns The frozen shared ok verdict, or a rejection carrying the resolved message / 共有の凍結 ok 判定、または解決済みメッセージ付きの拒否
+ * @throws {RangeError} When `locale` is not a supported SpreadsheetLocale (`undefined`, `null`,
+ * `"EN"`, `"ja-JP"`, ...), or the rule's `type` / `op` is outside the vocabulary / `locale` が
+ * 対応 SpreadsheetLocale でない場合 (`undefined`、`null`、`"EN"`、`"ja-JP"` など)、または規則の
+ * type / op が語彙外の場合
  */
-export const validateCellText = (rule: DataValidationRule, text: string, evaluate?: ValidationEvaluate): ValidationVerdict => {
+export const validateCellText = (rule: DataValidationRule, text: string, locale: SpreadsheetLocale, evaluate?: ValidationEvaluate): ValidationVerdict => {
+    // 型を外れた呼び手 (JS・as キャスト) の undefined を "en" へ黙って寄せると、言語の取り違えが表面化しない
+    if (typeof locale !== "string" || !Object.hasOwn(VALIDATION_MESSAGE_CATALOGS, locale)) {
+        const allowed = Object.keys(VALIDATION_MESSAGE_CATALOGS)
+            .map((candidate) => JSON.stringify(candidate))
+            .join(", ")
+        throw new RangeError(`[spreadsheet] validateCellText locale must be one of ${allowed}; got ${describeLabelValue(locale)}`)
+    }
     if (accepts(rule, text, evaluate)) {
         return VALID
     }
     // errorMessage は「置かれているか」だけを見る (空文字も consumer の意思として尊重)
-    return { ok: false, message: rule.errorMessage === undefined ? defaultMessage(rule) : rule.errorMessage }
+    return { ok: false, message: rule.errorMessage === undefined ? messageOf(rule, VALIDATION_MESSAGE_CATALOGS[locale]) : rule.errorMessage }
 }
 
 /** Whether a rule can be judged at paint time without a formula evaluator (every type but `custom`). / 数式評価器なしに描画時判定できる規則か (custom 以外の全型)。 */