@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/locale/messages-en.ts

@@ -0,0 +1,196 @@
+import type { ToolkitMessages } from "./message-types.js"
+
+/**
+ * English catalog — the fallback for every locale the toolkit does not ship.
+ * Sentence case, active voice, one "…" character for ellipses, no dashes as
+ * connectors; guarded by `toolkit-messages.test.ts`.
+ */
+export const en: ToolkitMessages = {
+  common: {
+    close: "Close",
+    retry: "Try again",
+    details: "Details",
+    dismiss: "Close notification",
+    notifications: "Notifications",
+    loadFailed: "This content couldn't be loaded",
+    loadFailedHint: "Try again. If it fails again, ask in the chat.",
+  },
+  view: {
+    loading: "Loading view…",
+    cancelled: "Cancelled. Ask in the chat to open this view again.",
+    refresh: "Refresh",
+    refreshing: "Refreshing…",
+    enterFullscreen: "Fullscreen",
+    exitFullscreen: "Exit fullscreen",
+    build: "Edit view",
+    slowHint: "This is taking longer than usual. If nothing happens, ask in the chat again.",
+    errorTitle: "This view couldn't be loaded",
+    errorHint: "Try again. If it fails again, ask in the chat.",
+    errorHintNoRetry: "Ask in the chat to open this view again.",
+    retry: "Try again",
+    blockedTitle: "The chat didn't pass the result to this view",
+    blockedHint: "Load the view yourself, or ask in the chat for the current state.",
+    blockedHintNoRetry:
+      "The action already ran, so the view doesn't start it again. Ask in the chat for the current state.",
+    blockedRetry: "Load view",
+    errorDetails: "Details",
+    stepErrorsTitle: "Some data couldn't be loaded",
+    stepErrorsHint: "Try again to load the missing data.",
+    refreshFailed: "Refresh didn't work.",
+    refreshFailedHint: "You're seeing the last loaded data. Try again in a moment.",
+    fullscreenFailed: "Couldn't switch the display mode.",
+    fullscreenFailedHint: "The view stays as it is. Try again in a moment.",
+    dataAsOf: (time) => `Reloaded at ${time}`,
+  },
+  listFooter: {
+    showing: ({ shown, total, noun }) => `Showing ${shown} of ${total} ${noun}`.trimEnd(),
+    defaultNoun: "rows",
+    loadMore: "Load more",
+    loadingMore: "Loading…",
+    updating: "Updating…",
+    noResults: "No entries",
+    refreshFailed: "Couldn't update the list",
+    refreshFailedHint: "You're seeing the previous result. Try again in a moment.",
+    loadMoreFailed: "Couldn't load more entries",
+    loadMoreFailedHint: "The entries above are current. Try again in a moment.",
+  },
+  filterBar: { searchPlaceholder: "Filter…", searchLabel: "Filter", chipsLabel: "Filters" },
+  pills: { live: "Live" },
+  renderer: {
+    widgetUnavailable: "This element isn't available in this version.",
+    widgetCrashed: "This element couldn't be displayed.",
+    noDataYet: "No data yet. It appears after the next refresh.",
+  },
+  builder: {
+    title: "Edit view",
+    builderBadge: "Editing",
+    previewBadge: "Preview",
+    catalogue: "Catalogue",
+    save: "Save as dashboard",
+    done: "Done",
+    apply: "Apply",
+    applyHint: "Shows your changes in this view and saves nothing.",
+    discard: "Discard",
+    discardHint: "Leaves the editor. The view stays as it was.",
+    discardHintStandalone: "Resets your changes.",
+    saveHint: "Saves the layout as a dashboard you can open again later.",
+    unsavedChanges: "Unsaved changes",
+    discardDialogTitle: "Discard your changes?",
+    discardDialogDescription:
+      "You lose your changes to this view. The view stays as it was before you edited it.",
+    discardDialogDescriptionSaved:
+      "The view goes back to how it was before you edited it. Your saved dashboard keeps your changes.",
+    keepEditing: "Keep editing",
+    discardConfirm: "Discard changes",
+    advanced: "Advanced",
+    advancedHint: "Shows the data sources, the catalogue and the technical IDs.",
+    renameTabNamed: (label) => `Rename tab “${label}”`,
+    removeTabNamed: (label) => `Remove tab “${label}”`,
+    rowTarget: "New elements go here",
+    stepProvides: "provides",
+    keyValueFor: (key) => (key ? `Value of ${key}` : "Value"),
+    viewLayoutTab: "Layout",
+    viewPipelineTab: "Data sources",
+    viewPreviewTab: "Preview",
+    saveDialogTitle: "Save as dashboard",
+    saveDialogDescription:
+      "Saves the layout and its data sources as a dashboard you can open again later. To change this view, use Apply.",
+    saveDialogDescriptionStandalone:
+      "Saves the layout and its data sources as a dashboard you can open again later.",
+    saveNameLabel: "Name",
+    saveDescriptionLabel: "Description",
+    saveConfirm: "Save dashboard",
+    cancel: "Cancel",
+    pipelineHeader: "Data sources",
+    keysHeader: "Keys",
+    stepsHeader: "Steps",
+    keyName: "Key",
+    keyValue: 'Value, "text", true, {…}',
+    stepContextId: "Step ID",
+    stepPickerLabel: "Pick a step",
+    addKey: "Add key",
+    addStep: "Add step",
+    emptyKeys: "No keys yet.",
+    emptySteps: "No steps yet.",
+    statusUpToDate: "Up to date",
+    statusPending: "Updating soon…",
+    statusRefreshing: "Updating…",
+    paletteHeader: "Elements",
+    paletteLoading: "Loading elements…",
+    paletteEmpty: "No elements available yet. Elements appear as soon as their data is there.",
+    canvasEmpty: "Drag an element here or click one in the list.",
+    canvasDropHint: "Drop to add",
+    addRow: "Add row",
+    addTab: "Add tab",
+    removeRow: "Remove row",
+    renameTab: "Rename tab",
+    removeTab: "Remove tab",
+    tabsLabel: "Tabs",
+    catalogueDescription: "Every key and element the server knows, available or not.",
+    catalogueKeys: "Keys",
+    catalogueSteps: "Steps",
+    catalogueUnreachable: "Unavailable elements",
+    catalogueUnreachableEmpty: "Every element is available.",
+    catalogueProducedBy: "produced by",
+    catalogueConsumedBy: "used by",
+    catalogueNeedsKeys: "needs",
+    cataloguePickKey: "Add as key",
+    catalogueAddProducingStep: "Add producing step",
+    catalogueLive: "live",
+    catalogueMissing: "missing",
+    catalogueError: "Couldn't refresh the catalogue",
+    catalogueErrorHint:
+      "The elements and data sources shown may be out of date. Try again. If it fails again, ask in the chat.",
+    validationWarning: "This view won't render as configured",
+    saveError: "The dashboard couldn't be saved",
+    saveErrorHint:
+      "Your changes are still here. Try saving again in a moment. If it fails again, ask in the chat.",
+    renameDuplicate: "A tab with that name already exists.",
+    statsLive: "live",
+    statsReachable: "available",
+    statsUnreachable: "unavailable",
+    emptyHintTitle: "No elements available yet.",
+    emptyHintBody:
+      "Add a key or a step under data sources. Elements appear as soon as their data is there.",
+    openDataSources: "Open data sources",
+    saveNamePlaceholder: "Name of the dashboard",
+    saveDescriptionPlaceholder: "Optional",
+    saved: (name) => `Dashboard “${name}” saved.`,
+    renameHint: "Rename a tab with F2, a double-click or its pencil button.",
+    renameTitle: "F2 or double-click to rename",
+    autoApplies: "Changes show in the preview right away",
+    noMoreKeys: "No more keys available.",
+    parsedType: "Detected type",
+    valueType: (code) =>
+      ({ str: "text", num: "number", bool: "yes/no", arr: "list", obj: "object", null: "empty" })[
+        code
+      ] ?? code,
+    removeKey: "Remove key",
+    removeStep: "Remove step",
+    noInputs: "no inputs",
+    noOutputs: "no outputs",
+    rowLabel: (index) => `Row ${index}`,
+    elementCount: (count) => (count === 1 ? "1 element" : `${count} elements`),
+    moveRowUp: "Move row up",
+    moveRowDown: "Move row down",
+    columnSpan: "Column span",
+    configureElement: "Configure element",
+    configureElementSet: (count) => `Configure element (${count} set)`,
+    removeElement: "Remove element",
+    resizeElement: "Resize element",
+    noKeysRegistered: "No keys registered.",
+    noStepsRegistered: "No steps registered.",
+    catalogueStepPrefix: "step",
+    catalogueElementPrefix: "element",
+  },
+  propsSheet: {
+    title: "Configure element",
+    description: "Settings for this element.",
+    apply: "Apply",
+    cancel: "Cancel",
+    reset: "Reset",
+    noProps: "This element has no settings.",
+    unsetOption: "Not set",
+    unsupportedType: (type) => `This field type (${type}) can't be edited here.`,
+  },
+}

package/src/locale/toolkit-messages.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, it } from "vitest"
+import {
+  formatClockTime,
+  formatCount,
+  resolveFormatLocale,
+  resolveToolkitLocale,
+  resolveToolkitMessages,
+  TOOLKIT_LOCALES,
+  TOOLKIT_MESSAGES,
+  type ToolkitMessages,
+} from "./toolkit-messages.js"
+
+/**
+ * The catalog guard: every toolkit string follows the house copy rules in
+ * BOTH locales (brand-tone: no dash as a connector, one "…" character, no
+ * framework jargon; German with du, AI not KI, "CIB seven"; English in
+ * sentence case), and the German catalog is a real translation, not a copy.
+ */
+
+/** Sample arguments for the function-valued messages. */
+const SAMPLES: Record<string, unknown[]> = {
+  showing: [{ shown: "8", total: "42", noun: "tasks" }],
+  saved: ["weekly ops"],
+  rowLabel: [3],
+  elementCount: [2],
+  configureElementSet: [2],
+  unsupportedType: ["array"],
+  valueType: ["num"],
+  renameTabNamed: ["Übersicht"],
+  removeTabNamed: ["Übersicht"],
+  keyValueFor: ["demo:id"],
+}
+
+/** Every message of a catalog as `[path, rendered text]`. */
+function flatten(messages: ToolkitMessages): [string, string][] {
+  const out: [string, string][] = []
+  for (const [section, entries] of Object.entries(messages)) {
+    for (const [key, value] of Object.entries(entries as Record<string, unknown>)) {
+      const text =
+        typeof value === "function"
+          ? (value as (...args: unknown[]) => string)(...(SAMPLES[key] ?? []))
+          : value
+      out.push([`${section}.${key}`, String(text)])
+    }
+  }
+  return out
+}
+
+const shape = (messages: ToolkitMessages) =>
+  Object.fromEntries(
+    Object.entries(messages).map(([section, entries]) => [
+      section,
+      Object.fromEntries(
+        Object.entries(entries as Record<string, unknown>).map(([k, v]) => [k, typeof v]),
+      ),
+    ]),
+  )
+
+describe("toolkit catalogs", () => {
+  it("ship en and de with the identical section/key shape and value kinds", () => {
+    expect(TOOLKIT_LOCALES).toEqual(["en", "de"])
+    expect(shape(TOOLKIT_MESSAGES.de)).toEqual(shape(TOOLKIT_MESSAGES.en))
+  })
+
+  for (const locale of TOOLKIT_LOCALES) {
+    describe(`${locale} copy rules`, () => {
+      const entries = flatten(TOOLKIT_MESSAGES[locale])
+
+      it("has no empty or padded message", () => {
+        for (const [path, text] of entries) {
+          expect(text.trim().length, path).toBeGreaterThan(0)
+          expect(text, path).toBe(text.trim())
+        }
+      })
+
+      it("uses no dash as a connector (A2) and the ellipsis character, never three dots", () => {
+        for (const [path, text] of entries) {
+          expect(text, path).not.toMatch(/—| – | - /)
+          expect(text, path).not.toContain("...")
+        }
+      })
+
+      it("speaks no framework jargon to users (no 'pipeline')", () => {
+        for (const [path, text] of entries) expect(text, path).not.toMatch(/pipeline/i)
+      })
+
+      it("writes the brand spellings (AI, CIB seven)", () => {
+        for (const [path, text] of entries) {
+          expect(text, path).not.toMatch(/\bKI\b/)
+          expect(text, path).not.toMatch(/CIB Seven|CIB SEVEN/)
+        }
+      })
+    })
+  }
+
+  it("de addresses the reader with du — never Sie/Ihnen/Ihr or an impersonal 'man'", () => {
+    for (const [path, text] of flatten(TOOLKIT_MESSAGES.de)) {
+      expect(text, path).not.toMatch(/\b(Sie|Ihnen|Ihr|Ihre|Ihren|Ihrem|Ihrer)\b/)
+      expect(text, path).not.toMatch(/\bman\b/)
+    }
+  })
+
+  it("en is in sentence case — no two capitalised words in a row within a sentence", () => {
+    const capitalised = (word: string) => /^[A-Z][a-z]/.test(word)
+    for (const [path, text] of flatten(TOOLKIT_MESSAGES.en)) {
+      const words = text.split(/\s+/)
+      for (let i = 1; i < words.length; i++) {
+        const prev = words[i - 1] ?? ""
+        const word = words[i] ?? ""
+        const titleCasePair = capitalised(prev) && !/[.!?:]$/.test(prev) && capitalised(word)
+        expect(titleCasePair, `${path}: "${prev} ${word}"`).toBe(false)
+      }
+    }
+  })
+
+  it("de is a translation: only loanwords may equal the English text", () => {
+    const en = new Map(flatten(TOOLKIT_MESSAGES.en))
+    const identical = flatten(TOOLKIT_MESSAGES.de)
+      .filter(([path, text]) => en.get(path) === text)
+      .map(([, text]) => text)
+    expect([...new Set(identical)].sort()).toEqual([
+      "Details",
+      "Layout",
+      "Live",
+      "Name",
+      "Optional",
+      "Tabs",
+    ])
+  })
+
+  it("renders counts and names into the parametrised messages", () => {
+    const { en, de } = TOOLKIT_MESSAGES
+    expect(en.listFooter.showing({ shown: "8", total: "42", noun: "tasks" })).toBe(
+      "Showing 8 of 42 tasks",
+    )
+    expect(de.listFooter.showing({ shown: "8", total: "42", noun: "Aufgaben" })).toBe(
+      "Zeigt 8 von 42 Aufgaben",
+    )
+    // An empty noun leaves no trailing blank.
+    expect(en.listFooter.showing({ shown: "1", total: "2", noun: "" })).toBe("Showing 1 of 2")
+    expect(de.listFooter.showing({ shown: "1", total: "2", noun: "" })).toBe("Zeigt 1 von 2")
+    expect(en.builder.saved("Ops")).toBe("Dashboard “Ops” saved.")
+    expect(de.builder.saved("Ops")).toBe("Dashboard „Ops“ gespeichert.")
+    expect(en.builder.elementCount(1)).toBe("1 element")
+    expect(en.builder.elementCount(3)).toBe("3 elements")
+    expect(de.builder.elementCount(1)).toBe("1 Element")
+    expect(de.builder.elementCount(0)).toBe("0 Elemente")
+    expect(en.builder.rowLabel(2)).toBe("Row 2")
+    expect(de.builder.rowLabel(2)).toBe("Zeile 2")
+    expect(en.builder.configureElementSet(2)).toBe("Configure element (2 set)")
+    expect(de.builder.configureElementSet(2)).toBe("Element konfigurieren (2 gesetzt)")
+    expect(en.builder.valueType("bool")).toBe("yes/no")
+    expect(de.builder.valueType("bool")).toBe("Ja/Nein")
+    expect(de.builder.valueType("arr")).toBe("Liste")
+    expect(en.builder.valueType("future")).toBe("future")
+    expect(de.builder.valueType("future")).toBe("future")
+    expect(en.propsSheet.unsupportedType("array")).toBe(
+      "This field type (array) can't be edited here.",
+    )
+    expect(de.propsSheet.unsupportedType("array")).toBe(
+      "Diesen Feldtyp (array) kannst du hier nicht bearbeiten.",
+    )
+    expect(en.builder.renameTabNamed("Ops")).toBe("Rename tab “Ops”")
+    expect(de.builder.renameTabNamed("Ops")).toBe("Tab „Ops“ umbenennen")
+    expect(en.builder.removeTabNamed("Ops")).toBe("Remove tab “Ops”")
+    expect(de.builder.removeTabNamed("Ops")).toBe("Tab „Ops“ entfernen")
+    expect(en.builder.keyValueFor("demo:id")).toBe("Value of demo:id")
+    expect(de.builder.keyValueFor("demo:id")).toBe("Wert von demo:id")
+    // A key row without a name yet still has an accessible name.
+    expect(en.builder.keyValueFor("")).toBe("Value")
+    expect(de.builder.keyValueFor("")).toBe("Wert")
+  })
+
+  it("builder: names Apply, Discard and Save apart in user words (U18)", () => {
+    const { en, de } = TOOLKIT_MESSAGES
+    expect([en.builder.apply, en.builder.discard, en.builder.save]).toEqual([
+      "Apply",
+      "Discard",
+      "Save as dashboard",
+    ])
+    expect([de.builder.apply, de.builder.discard, de.builder.save]).toEqual([
+      "Übernehmen",
+      "Verwerfen",
+      "Als Dashboard speichern",
+    ])
+    expect(de.builder.advanced).toBe("Erweitert")
+    // The refresh state no longer reuses the Apply verb.
+    for (const m of [en.builder, de.builder]) {
+      expect(m.statusPending).not.toMatch(/apply|übernomm/i)
+      expect(m.statusRefreshing).not.toMatch(/apply|übernomm/i)
+    }
+    // Rename is announced with its keyboard path, not double-click alone.
+    expect(en.builder.renameHint).toContain("F2")
+    expect(de.builder.renameHint).toContain("F2")
+    expect(en.builder.renameTitle).toContain("F2")
+    expect(de.builder.renameTitle).toContain("F2")
+  })
+})
+
+describe("resolveToolkitLocale", () => {
+  it("maps a BCP 47 tag onto its shipped primary language", () => {
+    expect(resolveToolkitLocale("de")).toBe("de")
+    expect(resolveToolkitLocale("de-DE")).toBe("de")
+    expect(resolveToolkitLocale("de_AT")).toBe("de")
+    expect(resolveToolkitLocale(" DE-ch ")).toBe("de")
+    expect(resolveToolkitLocale("en-US")).toBe("en")
+  })
+
+  it("falls back to English for any other or missing locale", () => {
+    expect(resolveToolkitLocale("fr-FR")).toBe("en")
+    expect(resolveToolkitLocale("")).toBe("en")
+    expect(resolveToolkitLocale(undefined)).toBe("en")
+    expect(resolveToolkitLocale("deu")).toBe("en")
+  })
+})
+
+describe("resolveToolkitMessages", () => {
+  it("returns the shipped catalog itself without an override (stable identity)", () => {
+    expect(resolveToolkitMessages("de-DE")).toBe(TOOLKIT_MESSAGES.de)
+    expect(resolveToolkitMessages("es")).toBe(TOOLKIT_MESSAGES.en)
+  })
+
+  it("merges an override per section and keeps every other string", () => {
+    const merged = resolveToolkitMessages("de", {
+      listFooter: { loadMore: "Weitere laden" },
+      view: { refresh: "Neu laden" },
+    })
+    expect(merged.listFooter.loadMore).toBe("Weitere laden")
+    expect(merged.listFooter.loadingMore).toBe(TOOLKIT_MESSAGES.de.listFooter.loadingMore)
+    expect(merged.view.refresh).toBe("Neu laden")
+    expect(merged.view.retry).toBe(TOOLKIT_MESSAGES.de.view.retry)
+    for (const section of [
+      "common",
+      "filterBar",
+      "pills",
+      "renderer",
+      "builder",
+      "propsSheet",
+    ] as const) {
+      expect(merged[section]).toEqual(TOOLKIT_MESSAGES.de[section])
+    }
+  })
+})
+
+describe("resolveToolkitMessages: the deprecated builder `done`", () => {
+  it("labels Apply with an override of `done`", () => {
+    const merged = resolveToolkitMessages("de", { builder: { done: "Los" } })
+    expect(merged.builder.apply).toBe("Los")
+    expect(merged.builder.done).toBe("Los")
+  })
+
+  it("keeps an `apply` override over `done`", () => {
+    const merged = resolveToolkitMessages("en", { builder: { done: "Finish", apply: "Show" } })
+    expect(merged.builder.apply).toBe("Show")
+  })
+
+  it("leaves Apply alone without a `done` override", () => {
+    expect(resolveToolkitMessages("en", { builder: { save: "Keep" } }).builder.apply).toBe(
+      TOOLKIT_MESSAGES.en.builder.apply,
+    )
+    expect(resolveToolkitMessages("de", { builder: { apply: "Zeigen" } }).builder.apply).toBe(
+      "Zeigen",
+    )
+    expect(resolveToolkitMessages("de", { view: { refresh: "Neu" } }).builder).toEqual(
+      TOOLKIT_MESSAGES.de.builder,
+    )
+  })
+})
+
+describe("formatCount", () => {
+  it("groups digits per locale", () => {
+    expect(formatCount(1234567, "en")).toBe("1,234,567")
+    expect(formatCount(1234567, "de-DE")).toBe("1.234.567")
+    expect(formatCount(7, "de")).toBe("7")
+  })
+
+  it("falls back to English for an invalid locale tag instead of throwing", () => {
+    expect(formatCount(1234, "not a locale!")).toBe("1,234")
+  })
+})
+
+describe("formatClockTime (the view's data-as-of stamp)", () => {
+  const at = Date.UTC(2026, 9, 11, 14, 32)
+
+  it("formats hours and minutes per locale in the host's time zone", () => {
+    expect(formatClockTime(at, "de-DE", "UTC")).toBe("14:32")
+    expect(formatClockTime(at, "de-DE", "Europe/Berlin")).toBe("16:32")
+    expect(formatClockTime(at, "en-GB", "UTC")).toBe("14:32")
+  })
+
+  it("never pads the hour of a 12-hour clock: 2:32 PM, not 02:32 PM", () => {
+    expect(formatClockTime(at, "en-US", "UTC")).toBe("2:32 PM")
+    expect(formatClockTime(Date.UTC(2026, 9, 11, 9, 5), "en-US", "UTC")).toBe("9:05 AM")
+    // Minutes keep two digits.
+    expect(formatClockTime(Date.UTC(2026, 9, 11, 14, 5), "de-DE", "UTC")).toBe("14:05")
+  })
+
+  it("a zone the runtime rejects drops the zone, never the locale", () => {
+    // Windows ids reach a view from some hosts; German stays a 24-hour clock.
+    expect(formatClockTime(at, "de", "W. Europe Standard Time")).toMatch(/^\d{2}:\d{2}$/)
+    expect(formatClockTime(at, "de-DE", "Not/AZone")).toMatch(/^\d{2}:\d{2}$/)
+    expect(formatClockTime(at, "en-US", "Not/AZone")).toMatch(/^[1-9]\d?:\d\d [AP]M$/)
+  })
+
+  it("an invalid tag falls back to English, in the host's zone when it is valid", () => {
+    expect(() => formatClockTime(at, "not a locale!", "UTC")).not.toThrow()
+    expect(formatClockTime(at, "not a locale!", "UTC")).toBe("2:32 PM")
+    expect(formatClockTime(at, "not a locale!", "Not/AZone")).toMatch(/^[1-9]\d?:\d\d [AP]M$/)
+  })
+
+  it("the catalogs stamp it in words that carry its meaning", () => {
+    expect(TOOLKIT_MESSAGES.en.view.dataAsOf("2:32 PM")).toBe("Reloaded at 2:32 PM")
+    expect(TOOLKIT_MESSAGES.de.view.dataAsOf("14:32")).toBe("Neu geladen um 14:32 Uhr")
+  })
+})
+
+describe("resolveFormatLocale (a time in the language of its sentence)", () => {
+  it("formats in the language the words come from, never the host's other language", () => {
+    // A German profile on an en-US host: German words, a German clock.
+    expect(resolveFormatLocale("de", "en-US")).toBe("de")
+    expect(resolveFormatLocale("en", "de-DE")).toBe("en")
+    expect(
+      formatClockTime(Date.UTC(2026, 9, 11, 14, 32), resolveFormatLocale("de", "en-US"), "UTC"),
+    ).toBe("14:32")
+  })
+
+  it("keeps the regional tag of the same language: en-GB keeps its 24-hour clock", () => {
+    expect(resolveFormatLocale("en", "en-GB")).toBe("en-GB")
+    expect(resolveFormatLocale("en-GB", "en-GB")).toBe("en-GB")
+    expect(resolveFormatLocale("de", "DE_AT")).toBe("DE-AT")
+    expect(resolveFormatLocale("  de ", "de-CH ")).toBe("de-CH")
+  })
+
+  it("prefers the text locale's own region over the host's", () => {
+    expect(resolveFormatLocale("en-GB", "en-US")).toBe("en-GB")
+    expect(resolveFormatLocale("de-AT", "de-DE")).toBe("de-AT")
+  })
+
+  it("maps a language without a catalog onto the catalog's, like the words", () => {
+    // French words fall back to English, so does their clock.
+    expect(resolveFormatLocale("fr-FR", "fr-FR")).toBe("en")
+    expect(resolveFormatLocale(undefined, "de-DE")).toBe("en")
+    expect(resolveFormatLocale(undefined, "en-AU")).toBe("en-AU")
+    expect(resolveFormatLocale("de")).toBe("de")
+    // A bare tag or a lookalike prefix is no region of the language.
+    expect(resolveFormatLocale("en", "en")).toBe("en")
+    expect(resolveFormatLocale("de", "dex-DE")).toBe("de")
+  })
+})

package/src/locale/toolkit-messages.ts

@@ -0,0 +1,143 @@
+/**
+ * The toolkit's own UI strings — every caption, label, placeholder and
+ * accessible name a toolkit component renders — as one typed catalog per
+ * locale. Components read the active locale's catalog through
+ * `useToolkitMessages()` (the nearest `LocaleProvider`), so a consumer only
+ * passes a locale; nothing in the toolkit hard-codes English any more.
+ *
+ * Pure data + functions (no React, no `mcp-use/react`): browser-safe and
+ * shared by the root barrel and the `./app` shell alike.
+ */
+import type { BuilderMessages, ToolkitMessages } from "./message-types.js"
+import { de } from "./messages-de.js"
+import { en } from "./messages-en.js"
+
+export type {
+  BuilderMessages,
+  CommonMessages,
+  FilterBarMessages,
+  ListFooterMessages,
+  PropsSheetMessages,
+  RendererMessages,
+  ToolkitMessages,
+  ViewMessages,
+} from "./message-types.js"
+
+/** A partial override of a {@link ToolkitMessages} catalog, per section. */
+export type ToolkitMessagesOverride = {
+  [K in keyof ToolkitMessages]?: Partial<ToolkitMessages[K]>
+}
+
+/** The locales the toolkit ships a catalog for. English is the fallback. */
+export const TOOLKIT_LOCALES = ["en", "de"] as const
+export type ToolkitLocale = (typeof TOOLKIT_LOCALES)[number]
+
+/** The shipped catalogs, keyed by {@link ToolkitLocale}. */
+export const TOOLKIT_MESSAGES: Readonly<Record<ToolkitLocale, ToolkitMessages>> = { en, de }
+
+/**
+ * Map any BCP 47 tag (`"de-DE"`, `"de_AT"`, `"EN"`) onto a shipped catalog:
+ * its primary language subtag when the toolkit ships it, English otherwise.
+ */
+export function resolveToolkitLocale(locale: string | undefined): ToolkitLocale {
+  const primary = (locale ?? "").trim().toLowerCase().split(/[-_]/)[0]
+  return (TOOLKIT_LOCALES as readonly string[]).includes(primary ?? "")
+    ? (primary as ToolkitLocale)
+    : "en"
+}
+
+/**
+ * The catalog for `locale`, with `override` merged over it section by
+ * section. Without an override the shipped catalog object itself is returned
+ * (referentially stable — safe as a memo dependency).
+ */
+export function resolveToolkitMessages(
+  locale: string | undefined,
+  override?: ToolkitMessagesOverride,
+): ToolkitMessages {
+  const base = TOOLKIT_MESSAGES[resolveToolkitLocale(locale)]
+  if (!override) return base
+  return {
+    common: { ...base.common, ...override.common },
+    view: { ...base.view, ...override.view },
+    listFooter: { ...base.listFooter, ...override.listFooter },
+    filterBar: { ...base.filterBar, ...override.filterBar },
+    pills: { ...base.pills, ...override.pills },
+    renderer: { ...base.renderer, ...override.renderer },
+    builder: mergeBuilder(base.builder, override.builder),
+    propsSheet: { ...base.propsSheet, ...override.propsSheet },
+  }
+}
+
+/**
+ * The builder section with its override. An override of the deprecated
+ * `done` still labels the commit button, Apply, unless it sets `apply` too.
+ */
+function mergeBuilder(
+  base: BuilderMessages,
+  override: Partial<BuilderMessages> | undefined,
+): BuilderMessages {
+  const merged = { ...base, ...override }
+  if (override?.done !== undefined && override.apply === undefined) merged.apply = override.done
+  return merged
+}
+
+/**
+ * Format a count for display in `locale` (grouping separators per locale:
+ * `1,234` / `1.234`). An invalid tag falls back to English instead of
+ * throwing inside a render.
+ */
+export function formatCount(value: number, locale: string | undefined): string {
+  try {
+    return new Intl.NumberFormat(locale).format(value)
+  } catch {
+    return new Intl.NumberFormat("en").format(value)
+  }
+}
+
+/**
+ * The tag a toolkit sentence formats its numbers and times in: the language
+ * its words come from (`textLocale`, mapped onto a shipped catalog the way
+ * {@link resolveToolkitMessages} maps it), with the regional tag of that
+ * language from `textLocale` or else `hostLocale`, so `en-GB` keeps its
+ * 24-hour clock. A tag of another language never mixes in: German words
+ * never carry an English clock ("Neu geladen um 4:32 PM Uhr").
+ */
+export function resolveFormatLocale(textLocale: string | undefined, hostLocale?: string): string {
+  const language = resolveToolkitLocale(textLocale)
+  const regionOfLanguage = (tag: string | undefined): string | undefined => {
+    const normal = tag?.trim().replace(/_/g, "-")
+    if (!normal?.includes("-")) return undefined
+    return normal.toLowerCase().split("-")[0] === language ? normal : undefined
+  }
+  return regionOfLanguage(textLocale) ?? regionOfLanguage(hostLocale) ?? language
+}
+
+/**
+ * Format the clock time (hours and minutes) of `epochMs` in `locale`, in the
+ * host's `timeZone` when it reports one: `14:32` / `2:32 PM`. The hour is
+ * `numeric`, so each locale pads it its own way (a 12-hour clock never shows
+ * `02:32 PM`). A zone the runtime rejects (a Windows id, say) drops the zone,
+ * never the locale; an invalid tag falls back to English. It never throws
+ * inside a render.
+ */
+export function formatClockTime(
+  epochMs: number,
+  locale: string | undefined,
+  timeZone?: string,
+): string {
+  const clock: Intl.DateTimeFormatOptions = { hour: "numeric", minute: "2-digit" }
+  const attempts: readonly (readonly [string | undefined, string | undefined])[] = [
+    [locale, timeZone],
+    [locale, undefined],
+    ["en", timeZone],
+  ]
+  for (const [tag, zone] of attempts) {
+    try {
+      return new Intl.DateTimeFormat(tag, { ...clock, timeZone: zone }).format(epochMs)
+    } catch {
+      // The next attempt drops what the runtime rejected.
+    }
+  }
+  return new Intl.DateTimeFormat("en", clock).format(epochMs)
+}