@spaethtech/svelte-ui 0.17.1-dev.84.05ecf9b → 0.18.0

package/.claude/skills/svelte-ui/SKILL.md

@@ -55,6 +55,40 @@ the components use:
 <Button text="Save" variant="primary" onclick={() => save(name)} />
 ```
 
+## Localization (i18n) — opt-in
+
+Components render their own microcopy (aria-labels, titles, "per page", "No results", month names…)
+through a message registry with **English defaults**. Do nothing → identical English output. To
+localize, call **`setUiI18n`** ONCE near the app root (a layout); partial `messages` merge over the
+defaults, so translate a subset and the rest stays English. `locale` also feeds the date components'
+`Intl.*` formatting (falls back to `navigator.language` when unset; a per-instance `locale` prop still
+overrides).
+
+```svelte
+<script>
+  import { setUiI18n } from "@spaethtech/svelte-ui";
+  import { getLocale } from "$lib/paraglide/runtime";
+  import { m } from "$lib/paraglide/messages";
+  setUiI18n({
+    locale: () => getLocale(),                       // getter ⇒ reactive; or a plain string
+    messages: () => ({
+      dismiss: m.ui_dismiss(),
+      selectAll: m.ui_select_all(),
+      rowRange: ({ start, end, total }) => m.ui_row_range({ start, end, total }), // "1–10 of 247"
+      removeFile: ({ name }) => m.ui_remove_file({ name }),
+      // …any subset of `UiMessages`
+    }),
+  });
+</script>
+```
+
+Parameterized entries are functions (`rowRange`, `removeFile`) — 1:1 with Paraglide's `m.key(params)`.
+Values may be plain or getters (getters make components re-render on locale change; plain is fine for
+per-navigation locale). Full key list: the `UiMessages` type; `defaultUiMessages` is the English source.
+Strings already exposed as PROPS (`Select placeholder`, `EmptyState title`, `CommandPalette empty`…) you
+localize directly on the component. **Authoring rule (this repo):** every new user-facing string a
+component renders must go through `uiI18n().messages` + `defaultUiMessages`, never a bare literal.
+
 ## The two shared axes (mirror each other)
 
 - **`variant`** — color/style: `primary` `secondary` `danger` `info` `success` `warning` `ghost`

package/CLAUDE.md

@@ -172,6 +172,17 @@ Two shared **cross-cutting axes** every sizeable/themeable component consumes (m
 
 ## Component Guidelines
 
+### Localization (i18n)
+
+Every user-facing string a component renders itself (aria-label, title, placeholder, fixed visible text,
+"per page"/"No results"/month names…) MUST go through the message registry, never a bare literal:
+add a key to `UiMessages` + `defaultUiMessages` in `src/lib/i18n.ts` (English default = the exact old
+literal, so output stays byte-identical), then render `i18n.messages.<key>` (`const i18n = uiI18n()`).
+Parameterized strings are functions (`rowRange({start,end,total})`) — never concatenate. Date/number
+formatting reads `i18n.locale` (fallback `navigator.language`; a per-instance `locale` prop overrides).
+Strings already exposed as a component PROP are localized by the consumer — leave those. A hard-coded
+user-facing literal in a component is a bug (it's invisible to `svelte-check` and to i18n consumers).
+
 ### Accessibility
 
 - All interactive components need keyboard support

package/dist/components/Badge/Badge.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import type { Snippet } from "svelte";
   import Close from "~icons/mdi/close";
   import type { Size } from "../../types/sizes.js";
@@ -143,7 +145,7 @@
         type="button"
         onclick={handleDismiss}
         onkeydown={handleKeydown}
-        aria-label="Dismiss"
+        aria-label={i18n.messages.dismiss}
         class="inline-flex items-center justify-center rounded-full hover:[background-color:color-mix(in_srgb,currentColor_15%,transparent)] focus:outline-none transition-colors duration-150"
       >
         <Close class={responsiveClasses(size, iconSizeClass)} />

package/dist/components/Banner.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
@@ -119,7 +121,7 @@
     {#if dismissible}
       <button
         type="button"
-        aria-label="Dismiss"
+        aria-label={i18n.messages.dismiss}
         onclick={close}
         class="inline-flex shrink-0 cursor-pointer items-center justify-center rounded p-0.5 opacity-80 transition-opacity hover:opacity-100 focus-visible:opacity-100 {responsiveClasses(
           size,

package/dist/components/Breadcrumbs/Breadcrumbs.svelte

@@ -17,6 +17,8 @@
 </script>
 
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import Button from "../Button.svelte";
   import Menu from "../Menu.svelte";
   import type { MenuItem } from "../../data/table/types.js";
@@ -71,7 +73,7 @@
   }
 </script>
 
-<nav aria-label="Breadcrumb" class={cls}>
+<nav aria-label={i18n.messages.breadcrumb} class={cls}>
   <ol
     class="flex flex-wrap items-center gap-1 [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]"
   >
@@ -91,7 +93,7 @@
       <li class="inline-flex items-center">
         {#if node.kind === "ellipsis"}
           <Button
-            title="Show more"
+            title={i18n.messages.showMore}
             variant="ghost"
             {size}
             aria-haspopup="menu"

package/dist/components/ButtonGroup/ButtonGroup.svelte

@@ -48,6 +48,8 @@
 </script>
 
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import Button from "../Button.svelte";
   import Menu from "../Menu.svelte";
   import type { Size } from "../../types/sizes.js";
@@ -225,7 +227,7 @@
             disabled={disabled || item.disabled}
             aria-haspopup="menu"
             aria-expanded={!!menuOpen[i]}
-            aria-label="More"
+            aria-label={i18n.messages.more}
             bind:element={caretRefs[i]}
             onclick={() => (menuOpen[i] = !menuOpen[i])}
           >

package/dist/components/Calendar.svelte

@@ -10,6 +10,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
@@ -43,7 +45,7 @@
     min,
     max,
     weekStart,
-    locale = typeof navigator !== "undefined" ? navigator.language : "en-US",
+    locale = i18n.locale ?? (typeof navigator !== "undefined" ? navigator.language : "en-US"),
     size = "md",
     variant = "primary",
     class: cls = "",
@@ -191,14 +193,14 @@
   <div class="mb-1 flex items-center justify-between {sizing.head}">
     <button
       type="button"
-      aria-label="Previous month"
+      aria-label={i18n.messages.prevMonth}
       class="grid {sizing.nav} place-items-center rounded-[var(--ui-border-radius)] hover:[background-color:var(--ui-color-hover)] active:[background-color:var(--ui-color-active)]"
       onclick={() => go(-1)}><IconLeft class="size-5" /></button
     >
     <span class="{sizing.label} font-medium">{monthLabel}</span>
     <button
       type="button"
-      aria-label="Next month"
+      aria-label={i18n.messages.nextMonth}
       class="grid {sizing.nav} place-items-center rounded-[var(--ui-border-radius)] hover:[background-color:var(--ui-color-hover)] active:[background-color:var(--ui-color-active)]"
       onclick={() => go(1)}><IconRight class="size-5" /></button
     >

package/dist/components/Carousel/Carousel.svelte

@@ -10,6 +10,8 @@
 </script>
 
 <script lang="ts" generics="T">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import Button from "../Button.svelte";
   import IconPrev from "~icons/mdi/chevron-left";
   import IconNext from "~icons/mdi/chevron-right";
@@ -106,7 +108,7 @@
   {#if controls && n > 1}
     <div class="absolute inset-y-0 left-2 flex items-center">
       <Button
-        title="Previous"
+        title={i18n.messages.previous}
         variant="secondary"
         onclick={prev}
         disabled={!loop && index === 0}
@@ -117,7 +119,7 @@
     </div>
     <div class="absolute inset-y-0 right-2 flex items-center">
       <Button
-        title="Next"
+        title={i18n.messages.next}
         variant="secondary"
         onclick={next}
         disabled={!loop && index === n - 1}

package/dist/components/CommandPalette/CommandPalette.svelte

@@ -20,6 +20,8 @@
 </script>
 
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import Input from "../Input.svelte";
   import Kbd from "../Kbd/Kbd.svelte";
   import IconSearch from "~icons/mdi/magnify";
@@ -143,7 +145,7 @@
       class="h-max w-full max-w-xl overflow-hidden rounded-[var(--ui-border-radius)] border shadow-2xl [background-color:var(--ui-color-background)] [border-color:var(--ui-border-color)]"
       role="dialog"
       aria-modal="true"
-      aria-label="Command palette"
+      aria-label={i18n.messages.commandPalette}
     >
       <Input
         bind:value={query}

package/dist/components/DataTable.svelte

@@ -10,6 +10,8 @@
  */
 -->
 <script lang="ts" generics="T">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Snippet } from "svelte";
   import IconDots from "~icons/mdi/dots-vertical";
   import IconBulk from "~icons/mdi/format-list-checks";
@@ -195,9 +197,11 @@
   }
 
   const rangeText = $derived(
-    total === 0
-      ? "0 of 0"
-      : `${(grid.page - 1) * grid.perPage + 1}–${Math.min(grid.page * grid.perPage, total)} of ${total}`,
+    i18n.messages.rowRange({
+      start: (grid.page - 1) * grid.perPage + 1,
+      end: Math.min(grid.page * grid.perPage, total),
+      total,
+    }),
   );
 
   // Invisible icon-slot sizing for the empty-state spacer. Sized to
@@ -246,7 +250,7 @@
         {#if selectable}
           <Checkbox
             {size}
-            aria-label="Select all"
+            aria-label={i18n.messages.selectAll}
             checked={grid.allSelected}
             indeterminate={grid.someSelected}
             onchange={() => grid.toggleAll()}
@@ -317,8 +321,8 @@
           <Button
             variant="ghost"
             {size}
-            aria-label="Bulk actions"
-            title="Bulk actions"
+            aria-label={i18n.messages.bulkActions}
+            title={i18n.messages.bulkActions}
             disabled={grid.selected.size === 0}
             onclick={(e) => openMenu(e, bulkActions(grid.selected))}
           >
@@ -352,7 +356,7 @@
         {/if}
         <div class="grow self-center text-center {subtle}">
           {#if settled}
-            No results.
+            {i18n.messages.noResults}.
           {:else}
             <span class="inline-flex items-center gap-2"
               ><IconLoading class="w-[1em] h-[1em] animate-spin" /> Loading…</span
@@ -381,7 +385,7 @@
                 {#if selectable}
                   <Checkbox
                     {size}
-                    aria-label="Select row"
+                    aria-label={i18n.messages.selectRow}
                     checked={grid.isSelected(id)}
                     onchange={() => grid.toggleRow(id)}
                   />
@@ -402,8 +406,8 @@
                   <Button
                     variant="ghost"
                     {size}
-                    aria-label="Move up"
-                    title="Move up"
+                    aria-label={i18n.messages.moveUp}
+                    title={i18n.messages.moveUp}
                     disabled={rowIndex === 0}
                     onclick={() => onReorder?.(row, "up")}
                   >
@@ -412,8 +416,8 @@
                   <Button
                     variant="ghost"
                     {size}
-                    aria-label="Move down"
-                    title="Move down"
+                    aria-label={i18n.messages.moveDown}
+                    title={i18n.messages.moveDown}
                     disabled={rowIndex === rows.length - 1}
                     onclick={() => onReorder?.(row, "down")}
                   >
@@ -454,8 +458,8 @@
                     variant="ghost"
                     {size}
                     disabled={!actions || actions.length === 0}
-                    aria-label="Row actions"
-                    title="Row actions"
+                    aria-label={i18n.messages.rowActions}
+                    title={i18n.messages.rowActions}
                     onclick={(e) => openMenu(e, actions ?? [])}
                   >
                     {#snippet icon()}<IconDots />{/snippet}
@@ -490,7 +494,7 @@
         options={grid.perPageOptions.map((n) => ({ value: String(n), label: String(n) }))}
         onSelection={(o) => grid.setPerPage(Number(o.value))}
       />
-      <span class={subtle}>per page</span>
+      <span class={subtle}>{i18n.messages.perPage}</span>
     </div>
 
     <div class="flex items-center gap-3">

package/dist/components/DatePicker.svelte

@@ -13,6 +13,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
@@ -57,7 +59,7 @@
     min,
     max,
     weekStart,
-    locale = typeof navigator !== "undefined" ? navigator.language : "en-US",
+    locale = i18n.locale ?? (typeof navigator !== "undefined" ? navigator.language : "en-US"),
     placeholder = range ? "Select dates" : time ? "Select date & time" : "Select date",
     disabled = false,
     size = "md",
@@ -195,7 +197,7 @@
   {#if hasValue && !disabled}
     <button
       type="button"
-      aria-label="Clear"
+      aria-label={i18n.messages.clear}
       tabindex="-1"
       class="grid size-5 place-items-center rounded {subtle} hover:[background-color:color-mix(in_srgb,var(--ui-color-text)_10%,transparent)]"
       onclick={(e) => {
@@ -207,7 +209,7 @@
   <button
     type="button"
     tabindex="-1"
-    aria-label="Open calendar"
+    aria-label={i18n.messages.openCalendar}
     {disabled}
     class="inline-flex items-center [color:var(--ui-color-secondary)] disabled:opacity-50"
     onclick={toggle}><IconCalendar /></button
@@ -235,7 +237,7 @@
       {#if time}
         <div class="mt-2 flex flex-col gap-2 border-t pt-2 [border-color:var(--ui-border-color)]">
           <div class="flex items-center gap-3">
-            <span class="w-10 shrink-0 text-xs {subtle}">Start</span><TimeSpinner
+            <span class="w-10 shrink-0 text-xs {subtle}">{i18n.messages.start}</span><TimeSpinner
               value={timeOf(rv.start)}
               {step}
               {seconds}
@@ -294,7 +296,7 @@
         <button
           type="button"
           class="rounded px-2 py-1 [color:var(--accent)] hover:underline"
-          onclick={goToday}>Today</button
+          onclick={goToday}>{i18n.messages.today}</button
         >
         {#if time}<span class={subtle}>/</span><button
             type="button"
@@ -305,7 +307,7 @@
       <button
         type="button"
         class="rounded px-2 py-1 {subtle} hover:underline"
-        onclick={() => (open = false)}>Done</button
+        onclick={() => (open = false)}>{i18n.messages.done}</button
       >
     </div>
   </div>

package/dist/components/FileUpload/FileUpload.svelte

@@ -7,6 +7,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import { onDestroy, untrack } from "svelte";
   import type { Snippet } from "svelte";
   import FieldChrome, { nextFieldId } from "../FieldChrome.svelte";
@@ -121,7 +123,7 @@
       <div
         role="button"
         tabindex={disabled ? -1 : 0}
-        aria-label="Upload files: drag and drop or activate to browse"
+        aria-label={i18n.messages.uploadFiles}
         aria-describedby={describedBy}
         class="flex flex-col items-center justify-center gap-2 rounded-[var(--ui-border-radius)] border-2 border-dashed text-center transition-colors {responsiveClasses(
           size,
@@ -194,8 +196,8 @@
                 {/if}
               </div>
               <Button
-                title="Remove {file.name}"
-                aria-label="Remove {file.name}"
+                title={i18n.messages.removeFile({ name: file.name })}
+                aria-label={i18n.messages.removeFile({ name: file.name })}
                 variant="ghost"
                 size="sm"
                 icon={removeIcon}

package/dist/components/List.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import { untrack } from "svelte";
   import type { Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
@@ -511,7 +513,7 @@
       onblur={handleListBlur}
       tabindex={disabled ? -1 : 0}
       role="listbox"
-      aria-label="List of options"
+      aria-label={i18n.messages.listOfOptions}
       aria-busy={isLoading}
       aria-disabled={disabled}
     >
@@ -626,7 +628,7 @@
         aria-valuemin="0"
         aria-valuemax="100"
         tabindex="-1"
-        aria-label="Scroll thumb"
+        aria-label={i18n.messages.scrollThumb}
       ></div>
     {/if}
   </div>

package/dist/components/NumberInput.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import { tick } from "svelte";
   import type { Snippet } from "svelte";
   import Input from "./Input.svelte";
@@ -321,8 +323,8 @@
     tabindex={-1}
     disabled={atMin}
     onclick={() => stepBy(-1)}
-    aria-label="Decrease"
-    title="Decrease"
+    aria-label={i18n.messages.decrease}
+    title={i18n.messages.decrease}
   >
     {#snippet icon()}<Minus />{/snippet}
   </Button>
@@ -332,8 +334,8 @@
     tabindex={-1}
     disabled={atMax}
     onclick={() => stepBy(1)}
-    aria-label="Increase"
-    title="Increase"
+    aria-label={i18n.messages.increase}
+    title={i18n.messages.increase}
   >
     {#snippet icon()}<Plus />{/snippet}
   </Button>

package/dist/components/Pagination/Pagination.svelte

@@ -8,6 +8,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import Button from "../Button.svelte";
   import Select from "../Select.svelte";
   import NumberInput from "../NumberInput.svelte";
@@ -66,9 +68,11 @@
   });
 
   const rangeText = $derived(
-    total <= 0
-      ? "0 of 0"
-      : `${(page - 1) * perPage + 1}–${Math.min(page * perPage, total)} of ${total}`,
+    i18n.messages.rowRange({
+      start: (page - 1) * perPage + 1,
+      end: Math.min(page * perPage, total),
+      total,
+    }),
   );
   const subtle = $derived(
     `${responsiveClasses(size, { sm: "text-xs", md: "text-sm", lg: "text-base" })} [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]`,
@@ -101,7 +105,7 @@
 </script>
 
 <nav
-  aria-label="Pagination"
+  aria-label={i18n.messages.pagination}
   class="ui-accent flex flex-wrap items-center justify-between gap-3 border rounded-[var(--ui-border-radius)] {bandPad} {cls}"
   style="border-color: {bandBorder}; background-color: {bandBg}; {accentVar}"
 >
@@ -115,7 +119,7 @@
         options={perPageOptions.map((n) => ({ value: String(n), label: String(n) }))}
         onSelection={(o) => setPerPage(Number(o.value))}
       />
-      <span class={subtle}>per page</span>
+      <span class={subtle}>{i18n.messages.perPage}</span>
     </div>
   {/if}
 
@@ -148,7 +152,7 @@
             {size}
             {disabled}
             inputClass="text-center px-1"
-            aria-label="Page number"
+            aria-label={i18n.messages.pageNumber}
             onchange={commitJump}
           />
         </span>

package/dist/components/Pagination/Pagination.svelte.d.ts

@@ -20,6 +20,6 @@ type $$ComponentProps = {
     disabled?: boolean;
     class?: string;
 };
-declare const Pagination: import("svelte").Component<$$ComponentProps, {}, "page" | "perPage">;
+declare const Pagination: import("svelte").Component<$$ComponentProps, {}, "perPage" | "page">;
 type Pagination = ReturnType<typeof Pagination>;
 export default Pagination;

package/dist/components/Query.svelte

@@ -7,6 +7,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import { tick } from "svelte";
   import IconSearch from "~icons/mdi/magnify";
   import IconClose from "~icons/mdi/close";
@@ -167,15 +169,15 @@
       {#snippet icon()}<IconSearch class="opacity-60" />{/snippet}
       {#snippet actions()}
         {#if dataset.query}
-          <Button variant="ghost" size="sm" aria-label="Clear" title="Clear" onclick={clear}
+          <Button variant="ghost" size="sm" aria-label={i18n.messages.clear} title={i18n.messages.clear} onclick={clear}
             >{#snippet icon()}<IconClose />{/snippet}</Button
           >
         {/if}
         <Button
           variant="ghost"
           size="sm"
-          aria-label="Query help"
-          title="Query help"
+          aria-label={i18n.messages.queryHelp}
+          title={i18n.messages.queryHelp}
           onclick={() => (helpOpen = true)}>{#snippet icon()}<IconHelp />{/snippet}</Button
         >
       {/snippet}
@@ -186,7 +188,7 @@
     <p class="mt-1 text-xs [color:var(--ui-color-error)]">{dataset.error}</p>
   {:else if dataset.dirty}
     <p class="mt-1 text-xs [color:color-mix(in_srgb,var(--ui-color-text)_50%,transparent)]">
-      Press <kbd class="rounded border px-1 {bc}">Enter</kbd> to apply
+      Press <kbd class="rounded border px-1 {bc}">{i18n.messages.enter}</kbd> to apply
     </p>
   {/if}
 </div>
@@ -225,7 +227,7 @@
   </ul>
 </Popup>
 
-<ConfirmDialog bind:isOpen={helpOpen} title="Query syntax" showConfirm={false} showCancel={false}>
+<ConfirmDialog bind:isOpen={helpOpen} title={i18n.messages.querySyntax} showConfirm={false} showCancel={false}>
   <div class="max-h-[70vh] space-y-4 overflow-y-auto text-sm [color:var(--ui-color-text)]">
     <p>
       A filter is one or more conditions, <code class="font-mono">$column operator value</code>.
@@ -233,7 +235,7 @@
       <code>()</code>.
     </p>
     <div>
-      <h4 class="mb-1 font-semibold">Operators</h4>
+      <h4 class="mb-1 font-semibold">{i18n.messages.operators}</h4>
       <table class="w-full text-left">
         <tbody class="[&_td]:py-0.5 [&_td:first-child]:pr-4 [&_td:first-child]:font-mono">
           <tr><td>== !=</td><td>equals / not equals</td></tr>
@@ -246,7 +248,7 @@
       </table>
     </div>
     <div>
-      <h4 class="mb-1 font-semibold">Casts</h4>
+      <h4 class="mb-1 font-semibold">{i18n.messages.casts}</h4>
       <p class="mb-1 text-xs [color:color-mix(in_srgb,var(--ui-color-text)_70%,transparent)]">
         A <code class="font-mono">|type</code> after a column or value forces its type for strict comparison
         — one cast per clause; put it on the column and/or the literals.
@@ -282,7 +284,7 @@
       </table>
     </div>
     <div>
-      <h4 class="mb-1 font-semibold">Examples</h4>
+      <h4 class="mb-1 font-semibold">{i18n.messages.examples}</h4>
       <table class="w-full text-left">
         <tbody
           class="[&_td]:py-0.5 [&_td:first-child]:whitespace-nowrap [&_td:first-child]:pr-4 [&_td:first-child]:font-mono [&_td:last-child]:text-xs [&_td:last-child]:[color:color-mix(in_srgb,var(--ui-color-text)_65%,transparent)]"
@@ -305,7 +307,7 @@
     </div>
     <p class="text-xs [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]">
       Tip: type <kbd class="rounded border px-1 {bc}">$</kbd> for columns; enum columns suggest
-      values. Applies on <kbd class="rounded border px-1 {bc}">Enter</kbd>.
+      values. Applies on <kbd class="rounded border px-1 {bc}">{i18n.messages.enter}</kbd>.
     </p>
   </div>
 </ConfirmDialog>

package/dist/components/Stepper/Stepper.svelte

@@ -11,6 +11,8 @@
 </script>
 
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   import IconCheck from "~icons/mdi/check";
   import type { Variant } from "../../types/variants.js";
   import { variantToken } from "../../types/variants.js";
@@ -61,7 +63,7 @@
 
 <ol
   class="flex {isH ? 'flex-row items-start' : 'flex-col'} {cls}"
-  aria-label="Progress"
+  aria-label={i18n.messages.progress}
 >
   {#each steps as step, i (i)}
     {@const s = state(i)}

package/dist/components/TextArea.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import ContentCopy from "~icons/mdi/content-copy";
   import type { HTMLTextareaAttributes } from "svelte/elements";
   import type { Snippet } from "svelte";
@@ -705,7 +707,7 @@
           updateScrollbar();
         }}
     role="group"
-    aria-label="Text area with controls"
+    aria-label={i18n.messages.textAreaControls}
   >
     <textarea
       bind:this={textareaElement}
@@ -747,7 +749,7 @@
         role="button"
         tabindex="0"
         style="user-select: none; -webkit-user-select: none; -moz-user-select: none; -ms-user-select: none;"
-        title="Copy to clipboard"
+        title={i18n.messages.copyToClipboard}
       >
         <ContentCopy
           class="w-4 h-4 [color:var(--ui-color-secondary)!important] group-hover:[color:color-mix(in_srgb,var(--ui-color-secondary)_80%,black)!important] group-focus:[color:color-mix(in_srgb,currentColor_70%,transparent)!important] transition-colors"
@@ -774,7 +776,7 @@
         aria-valuemin="0"
         aria-valuemax="100"
         tabindex="-1"
-        aria-label="Scroll thumb"
+        aria-label={i18n.messages.scrollThumb}
       ></div>
     {/if}
     </div>

package/dist/components/ThemeSelector.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import Select from "./Select.svelte";
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
@@ -40,7 +42,7 @@
     {options}
     {size}
     {variant}
-    placeholder="Select theme..."
+    placeholder={i18n.messages.selectTheme}
     class="w-40"
   />
 </div>

package/dist/components/TimeRangeInput.svelte

@@ -9,6 +9,8 @@
  */
 -->
 <script lang="ts">
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import { resolveStep, type StepSpec } from "../types/time.js";
@@ -128,7 +130,7 @@
   {#if hasValue && !disabled}
     <button
       type="button"
-      aria-label="Clear"
+      aria-label={i18n.messages.clear}
       tabindex="-1"
       class="grid size-5 place-items-center rounded {subtle} hover:[background-color:color-mix(in_srgb,var(--ui-color-text)_10%,transparent)]"
       onclick={(e) => {
@@ -140,7 +142,7 @@
   <button
     type="button"
     tabindex="-1"
-    aria-label="Open time range"
+    aria-label={i18n.messages.openTimeRange}
     {disabled}
     class="inline-flex items-center [color:var(--ui-color-secondary)] disabled:opacity-50"
     onclick={toggle}><IconClock /></button

package/dist/components/Toast/Toaster.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { uiI18n } from "../../i18n.js";
+  const i18n = uiI18n();
   /**
    * Renders the toast store's items in a fixed, top-layer stack. Mount ONCE at the app root; push with
    * `toast.*` from anywhere. Each toast is an Alert (filled) honouring its variant + size.
@@ -41,7 +43,7 @@
         >
         <button
           type="button"
-          aria-label="Dismiss"
+          aria-label={i18n.messages.dismiss}
           class="shrink-0 self-center pr-2 opacity-60 hover:opacity-100"
           onclick={() => dismissToast(t.id)}><IconClose class="size-4" /></button
         >

package/dist/i18n.d.ts

@@ -0,0 +1,88 @@
+/** A message: a fixed string, or a function of named params (mirrors Paraglide's `m.key(params)`). */
+type Msg = string;
+type MsgFn<P> = (params: P) => string;
+/**
+ * Every user-facing string svelte-ui renders itself. Parameterized entries are functions so word order
+ * stays translatable. Strings already exposed as component PROPS (Select `placeholder`, EmptyState
+ * `title`, CommandPalette `placeholder`/`empty`, …) are localized by the consumer directly and are NOT
+ * here.
+ */
+export type UiMessages = {
+    dismiss: Msg;
+    clear: Msg;
+    more: Msg;
+    showMore: Msg;
+    copyToClipboard: Msg;
+    done: Msg;
+    noResults: Msg;
+    previous: Msg;
+    next: Msg;
+    first: Msg;
+    last: Msg;
+    pagination: Msg;
+    pageNumber: Msg;
+    perPage: Msg;
+    rowRange: MsgFn<{
+        start: number;
+        end: number;
+        total: number;
+    }>;
+    breadcrumb: Msg;
+    scrollThumb: Msg;
+    progress: Msg;
+    commandPalette: Msg;
+    selectDate: Msg;
+    openCalendar: Msg;
+    prevMonth: Msg;
+    nextMonth: Msg;
+    today: Msg;
+    start: Msg;
+    dynamicDates: Msg;
+    openTimeRange: Msg;
+    bulkActions: Msg;
+    selectAll: Msg;
+    selectRow: Msg;
+    rowActions: Msg;
+    moveUp: Msg;
+    moveDown: Msg;
+    listOfOptions: Msg;
+    increase: Msg;
+    decrease: Msg;
+    textAreaControls: Msg;
+    uploadFiles: Msg;
+    removeFile: MsgFn<{
+        name: string;
+    }>;
+    queryHelp: Msg;
+    querySyntax: Msg;
+    casts: Msg;
+    operators: Msg;
+    examples: Msg;
+    notes: Msg;
+    enter: Msg;
+    selectTheme: Msg;
+    menu: Msg;
+};
+/** English defaults — the exact literals the components used to hard-code (no behaviour change). */
+export declare const defaultUiMessages: UiMessages;
+/** What a component reads. `locale` is `undefined` unless a provider sets one — Intl components then
+ *  fall back to `navigator.language`, preserving current behaviour for no-op consumers. */
+export type UiI18n = {
+    readonly locale: string | undefined;
+    readonly messages: UiMessages;
+};
+type Resolvable<T> = T | (() => T);
+type UiI18nConfig = {
+    locale?: Resolvable<string | undefined>;
+    messages?: Resolvable<Partial<UiMessages>>;
+};
+/**
+ * Provide svelte-ui's localization. Call ONCE near the app root. Partial `messages` merge over the
+ * English defaults, so translating a subset leaves the rest English. Values may be getters for a
+ * runtime-switchable locale.
+ */
+export declare function setUiI18n(config: UiI18nConfig): void;
+/** Read the active messages + locale. Falls back to English defaults / `undefined` locale when no
+ *  provider is present. Reads lazily, so getters passed to `setUiI18n` make components reactive. */
+export declare function uiI18n(): UiI18n;
+export {};

package/dist/i18n.js

@@ -0,0 +1,84 @@
+// svelte-ui internal localization. Components render their own microcopy (aria-labels, titles, fixed
+// visible text) through a small message registry with English defaults, and read a display `locale`
+// for `Intl.*` formatting. A consumer overrides once at the app root via `setUiI18n`; do nothing and
+// every string is the English default (byte-identical output — i18n is fully opt-in).
+//
+// Reactivity: `setUiI18n` accepts concrete values OR getter functions. Pass getters that read reactive
+// state (e.g. `() => getLocale()`) and components re-render on locale change; pass plain values for a
+// static (per-navigation) locale. Reads happen lazily in each component's reactive scope.
+import { getContext, setContext } from "svelte";
+/** English defaults — the exact literals the components used to hard-code (no behaviour change). */
+export const defaultUiMessages = {
+    dismiss: "Dismiss",
+    clear: "Clear",
+    more: "More",
+    showMore: "Show more",
+    copyToClipboard: "Copy to clipboard",
+    done: "Done",
+    noResults: "No results",
+    previous: "Previous",
+    next: "Next",
+    first: "First",
+    last: "Last",
+    pagination: "Pagination",
+    pageNumber: "Page number",
+    perPage: "per page",
+    rowRange: ({ start, end, total }) => (total <= 0 ? "0 of 0" : `${start}–${end} of ${total}`),
+    breadcrumb: "Breadcrumb",
+    scrollThumb: "Scroll thumb",
+    progress: "Progress",
+    commandPalette: "Command palette",
+    selectDate: "Select date",
+    openCalendar: "Open calendar",
+    prevMonth: "Previous month",
+    nextMonth: "Next month",
+    today: "Today",
+    start: "Start",
+    dynamicDates: "Dynamic dates",
+    openTimeRange: "Open time range",
+    bulkActions: "Bulk actions",
+    selectAll: "Select all",
+    selectRow: "Select row",
+    rowActions: "Row actions",
+    moveUp: "Move up",
+    moveDown: "Move down",
+    listOfOptions: "List of options",
+    increase: "Increase",
+    decrease: "Decrease",
+    textAreaControls: "Text area with controls",
+    uploadFiles: "Upload files: drag and drop or activate to browse",
+    removeFile: ({ name }) => `Remove ${name}`,
+    queryHelp: "Query help",
+    querySyntax: "Query syntax",
+    casts: "Casts",
+    operators: "Operators",
+    examples: "Examples",
+    notes: "Notes",
+    enter: "Enter",
+    selectTheme: "Select theme...",
+    menu: "Menu",
+};
+const KEY = Symbol("svelte-ui-i18n");
+const resolve = (v) => typeof v === "function" ? v() : v;
+/**
+ * Provide svelte-ui's localization. Call ONCE near the app root. Partial `messages` merge over the
+ * English defaults, so translating a subset leaves the rest English. Values may be getters for a
+ * runtime-switchable locale.
+ */
+export function setUiI18n(config) {
+    setContext(KEY, config);
+}
+/** Read the active messages + locale. Falls back to English defaults / `undefined` locale when no
+ *  provider is present. Reads lazily, so getters passed to `setUiI18n` make components reactive. */
+export function uiI18n() {
+    const cfg = getContext(KEY);
+    return {
+        get locale() {
+            return resolve(cfg?.locale);
+        },
+        get messages() {
+            const overrides = resolve(cfg?.messages);
+            return overrides ? { ...defaultUiMessages, ...overrides } : defaultUiMessages;
+        },
+    };
+}

package/dist/index.d.ts

@@ -82,6 +82,8 @@ export { anchored, computePlacement, resolveBoundary } from "./positioning/ancho
 export type { Side, Align, Boundary, PlaceOptions, Placement, AnchoredParams, } from "./positioning/anchored.js";
 export { tooltip } from "./positioning/tooltip.js";
 export type { TooltipOptions } from "./positioning/tooltip.js";
+export { setUiI18n, uiI18n, defaultUiMessages } from "./i18n.js";
+export type { UiMessages, UiI18n } from "./i18n.js";
 export type { Variant } from "./types/variants.js";
 export type { Size } from "./types/sizes.js";
 export type { StepSpec } from "./types/time.js";

package/dist/index.js

@@ -78,5 +78,7 @@ export { default as Query } from "./components/Query.svelte";
 export { anchored, computePlacement, resolveBoundary } from "./positioning/anchored.js";
 // Tooltip action (use:tooltip) — themed tooltips on the `anchored` engine, no global handler.
 export { tooltip } from "./positioning/tooltip.js";
+// Internal localization (opt-in) — override svelte-ui's own microcopy + Intl locale at the app root.
+export { setUiI18n, uiI18n, defaultUiMessages } from "./i18n.js";
 export { BREAKPOINT_PX } from "./types/breakpoints.js";
 export { responsiveClasses, resolveScalar } from "./types/responsive.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.17.1-dev.84.05ecf9b",
+  "version": "0.18.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"