@lotics/ui 6.0.0 → 6.2.0

package/AGENTS.md

@@ -12,9 +12,18 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
   `PortalHost` at the app root.
 - RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
   `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
-- i18n: most components are string-free; the few that emit their own user-facing strings take
-  a `labels` prop (`DateRangeFilterField`, `Pagination`, `SortHeader`/`Table.sortLabels`,
-  `RemainderMeter`) — localize there.
+- i18n: most components are string-free. For the rest, set the language ONCE at the root with
+  **`LoticsLocaleProvider`** (`@lotics/ui/locale`, the sibling of `LoticsThemeProvider`) — wrap
+  `<LoticsLocaleProvider locale={vi}>` and every wired component picks up the pack, no per-instance
+  props. Shipped packs: `en` (default) and `vi` (one canonical Vietnamese translation, so apps don't
+  redefine — or drift on — strings). Resolution is **prop → provider locale → English default**, so a
+  per-instance `labels`/`clearLabel`/`selectAllLabel` still overrides for one-offs, and an un-wrapped
+  app stays English. Wired so far: `Pagination`, `SortHeader`/`Table.sortLabels`, `OptionList`
+  (+ `Select`/`Combobox` built on it), `FilterChip`, `Drawer`, `Confidence`, `RemainderMeter`,
+  `ChangeReview`/`ChangeReviewActions`, and `DateRangeFilterField`/`DateFilter` (presets + footer +
+  time-segment a11y, one `dateRange` slice). Adding a string to a wired component's `*Labels` forces
+  both packs in `locale.tsx` to fill it (compile error) — that's how the kit avoids a silent English
+  leak. Not yet on the provider (pass `labels` for now): calendar/gantt, the file/preview/comment labels.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -56,6 +56,7 @@
     "./status_grid": "./src/status_grid.tsx",
     "./heatmap": "./src/heatmap.tsx",
     "./trend_footer": "./src/trend_footer.tsx",
+    "./locale": "./src/locale.tsx",
     "./spacing": "./src/spacing.ts",
     "./theme": "./src/theme.tsx",
     "./progress_bar": "./src/progress_bar.tsx",

package/src/change_review.tsx

@@ -5,6 +5,7 @@ import { reviewCardStyle, reviewResolvedStyle } from "./control_surface";
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { Button } from "./button";
+import { useLoticsLocale } from "./locale";
 
 export type ChangeReviewItemStatus = "pending" | "accepted" | "rejected";
 
@@ -116,17 +117,18 @@ export function ChangeDiff({ before, after }: { before?: string; after: string }
  * `ReviewCard` reviews a SINGLE proposal, this is the BATCH engine.
  */
 export function ChangeReview<T>(props: ChangeReviewProps<T>) {
+  const loc = useLoticsLocale().changeReview;
   const status = props.status ?? "open";
   const perItem = props.onAcceptItem != null || props.onRejectItem != null;
   const total = props.items.length;
   const statusFor = (item: T, i: number) => props.statusOf?.(item, i) ?? "pending";
   const keptCount = props.items.filter((it, i) => statusFor(it, i) === "accepted").length;
-  const title = props.title ?? "Suggested edits";
+  const title = props.title ?? loc.title;
   const L = {
-    undo: "Undo",
-    applied: "Applied",
-    discarded: "Discarded",
-    keptCount: (kept: number, total: number) => `${kept} of ${total} kept`,
+    undo: loc.undo,
+    applied: loc.applied,
+    discarded: loc.discarded,
+    keptCount: loc.keptCount,
     ...props.labels,
   };
 
@@ -173,8 +175,8 @@ export function ChangeReview<T>(props: ChangeReviewProps<T>) {
                   <View key={props.getKey(item, i)} style={styles.itemCard}>
                     {props.renderItem(item, i)}
                     <View style={styles.itemActions}>
-                      <Button title={props.rejectLabel ?? "Drop"} color="muted" onPress={() => props.onRejectItem?.(i)} />
-                      <Button title={props.acceptLabel ?? "Keep"} color="secondary" onPress={() => props.onAcceptItem?.(i)} />
+                      <Button title={props.rejectLabel ?? loc.reject} color="muted" onPress={() => props.onRejectItem?.(i)} />
+                      <Button title={props.acceptLabel ?? loc.accept} color="secondary" onPress={() => props.onAcceptItem?.(i)} />
                     </View>
                   </View>
                 );
@@ -233,6 +235,7 @@ export function ChangeReview<T>(props: ChangeReviewProps<T>) {
  * inline wrapper provides the chrome); self-hides once `status` isn't open.
  */
 export function ChangeReviewActions<T>(props: ChangeReviewActionsProps<T>) {
+  const loc = useLoticsLocale().changeReview;
   if ((props.status ?? "open") !== "open") return null;
   const perItem = props.onAcceptItem != null;
   const statusFor = (item: T, i: number) => props.statusOf?.(item, i) ?? "pending";
@@ -243,12 +246,12 @@ export function ChangeReviewActions<T>(props: ChangeReviewActionsProps<T>) {
     });
   return (
     <View style={styles.actionsRow}>
-      {perItem ? <Button title={props.acceptAllLabel ?? "Accept all"} color="muted" onPress={acceptAll} /> : null}
+      {perItem ? <Button title={props.acceptAllLabel ?? loc.acceptAll} color="muted" onPress={acceptAll} /> : null}
       <View style={{ flex: 1 }} />
-      {props.onDiscard ? <Button title={props.discardLabel ?? "Discard"} color="muted" onPress={props.onDiscard} /> : null}
+      {props.onDiscard ? <Button title={props.discardLabel ?? loc.discard} color="muted" onPress={props.onDiscard} /> : null}
       {props.onApply ? (
         <Button
-          title={props.applyLabel ?? (perItem ? "Apply kept" : "Apply")}
+          title={props.applyLabel ?? (perItem ? loc.applyKept : loc.apply)}
           color="primary"
           disabled={perItem && keptCount === 0}
           onPress={props.onApply}

package/src/column_filter.tsx

@@ -92,7 +92,8 @@ export interface ColumnFilterProps {
   column: FilterableColumn;
   value: ColumnFilterValue | undefined;
   onChange: (value: ColumnFilterValue | undefined) => void;
-  /** Accessible name for the clear (X) control. Pass a translated string. Default "Clear". */
+  /** Accessible name for the clear (X) control. Omit to use the locale's
+   *  `filterChip.clear` (English "Clear" by default). */
   clearLabel?: string;
 }
 
@@ -105,7 +106,7 @@ export interface ColumnFilterProps {
  * `columnFilterToConditions`. Pure UI; no data layer.
  */
 export function ColumnFilter(props: ColumnFilterProps) {
-  const { column, value, onChange, clearLabel = "Clear" } = props;
+  const { column, value, onChange, clearLabel } = props;
   const active = isColumnFilterActive(value);
 
   return (

package/src/combobox.tsx

@@ -9,6 +9,7 @@ import {
 import { useCallback, useRef, useState, type ReactNode } from "react";
 import { colors } from "./colors";
 import { FOCUS_RING } from "./control_surface";
+import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { TextInputField } from "./text_input_field";
@@ -110,8 +111,6 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     searchDebounceMs = 200,
     icon,
     placeholder,
-    recentsLabel = "Recent",
-    emptyText = "No results",
     accessibilityLabel = "Results",
     disabled = false,
     clearable = false,
@@ -121,6 +120,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     testID,
     style,
   } = props;
+  const loc = useLoticsLocale().optionList;
+  const emptyText = props.emptyText ?? loc.noResults;
+  const recentsLabel = props.recentsLabel ?? loc.recent;
 
   const single = value ?? null;
   const reflectedText = single ? (single.label ?? single.value) : "";

package/src/confidence.tsx

@@ -1,6 +1,7 @@
 import { StyleSheet, View } from "react-native";
 import { colors, solid, type ColorName } from "./colors";
 import { Text } from "./text";
+import { useLoticsLocale } from "./locale";
 
 export type ConfidenceLevel = "high" | "medium" | "low";
 
@@ -20,7 +21,6 @@ export interface ConfidenceProps {
   labels?: Partial<ConfidenceLabels>;
 }
 
-const DEFAULT_LABELS: ConfidenceLabels = { high: "High confidence", medium: "Medium confidence", low: "Low confidence" };
 const FILLED: Record<ConfidenceLevel, number> = { high: 3, medium: 2, low: 1 };
 // high emerald, medium amber, low zinc (unsure — not an error). One family per
 // level; the fill count AND the colour both carry it.
@@ -40,7 +40,7 @@ export function levelFromScore(score: number): ConfidenceLevel {
  */
 export function Confidence(props: ConfidenceProps) {
   const level = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");
-  const l = { ...DEFAULT_LABELS, ...props.labels };
+  const l = { ...useLoticsLocale().confidence, ...props.labels };
   const filled = FILLED[level];
   const fill = solid(COLOR[level]);
   return (

package/src/date_filter.tsx

@@ -11,6 +11,7 @@ import { useScreenSize } from "./use_screen_size";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
 import { formatDate } from "./format_date";
+import { useLoticsLocale } from "./locale";
 
 type SelectionMode = "single" | "range";
 
@@ -42,25 +43,6 @@ export interface DateFilterLabels extends SegmentLabels {
   selectDate: string;
 }
 
-const DEFAULT_LABELS: DateFilterLabels = {
-  year: "Year",
-  month: "Month",
-  day: "Day",
-  hour: "Hour",
-  minute: "Minute",
-  dayPeriod: "AM/PM",
-  today: "Today",
-  yesterday: "Yesterday",
-  tomorrow: "Tomorrow",
-  thisWeek: "This week",
-  thisMonth: "This month",
-  lastMonth: "Last month",
-  custom: "Custom",
-  from: "From",
-  to: "To",
-  selectDateRange: "Select date range",
-  selectDate: "Select date",
-};
 
 export interface DateFilterProps {
   value: DateFilterValue;
@@ -106,9 +88,10 @@ function formatDateDisplay(date: Date | null, locale: string | undefined): strin
 
 export function DateFilter(props: DateFilterProps) {
   const { value, onValueChange, includeTime = false, locale } = props;
+  const loc = useLoticsLocale().dateRange;
   const labels = useMemo<DateFilterLabels>(
-    () => ({ ...DEFAULT_LABELS, ...props.labels }),
-    [props.labels],
+    () => ({ ...loc, ...props.labels }),
+    [loc, props.labels],
   );
   const screenSize = useScreenSize();
   const calendarRef = useRef<CalendarRef>(null);

package/src/date_range_filter_field.tsx

@@ -9,6 +9,7 @@ import { PressableHighlight } from "./pressable_highlight";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import { DateFilter, DateFilterValue, DateFilterLabels } from "./date_filter";
 import { formatDate } from "./format_date";
+import { useLoticsLocale } from "./locale";
 
 // =============================================================================
 // DateRangeFilterField — the common filter composition over DateFilter:
@@ -27,7 +28,6 @@ export interface DateRangeFilterFieldLabels extends DateFilterLabels {
   placeholder: string;
 }
 
-const DEFAULT_FIELD_LABELS = { clear: "Clear", done: "Done", placeholder: "All time" };
 
 export interface DateRangeFilterFieldProps {
   value: DateFilterValue;
@@ -110,7 +110,8 @@ function formatTrigger(value: DateFilterValue, includeTime: boolean, locale: str
 
 export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
   const { value, onValueChange, includeTime, locale, testID } = props;
-  const labels = useMemo(() => ({ ...DEFAULT_FIELD_LABELS, ...props.labels }), [props.labels]);
+  const loc = useLoticsLocale().dateRange;
+  const labels = useMemo(() => ({ ...loc, ...props.labels }), [loc, props.labels]);
   const [open, setOpen] = useState(false);
 
   const hasValue = Boolean(value.start.date || value.end.date);

package/src/drawer.tsx

@@ -6,6 +6,7 @@ import { colors } from "@lotics/ui/colors";
 import { IconButton } from "@lotics/ui/icon_button";
 import { Text } from "@lotics/ui/text";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
+import { useLoticsLocale } from "@lotics/ui/locale";
 
 export interface DrawerProps {
   open: boolean;
@@ -44,6 +45,7 @@ export interface DrawerProps {
  */
 export function Drawer(props: DrawerProps) {
   const { open, onOpenChange, title, width = 420, onPrev, onNext, position, children, testID } = props;
+  const loc = useLoticsLocale().drawer;
   const screenSize = useScreenSize();
   useOverlayScope(open);
   const handleClose = () => onOpenChange(false);
@@ -79,7 +81,7 @@ export function Drawer(props: DrawerProps) {
     <Modal visible={open} onRequestClose={handleClose} transparent>
       <View style={styles.base}>
         {/* Scrim is a sibling of the panel, so tapping the panel never closes. */}
-        <Pressable style={styles.scrim} onPress={handleClose} accessibilityLabel="Close" tabIndex={-1} />
+        <Pressable style={styles.scrim} onPress={handleClose} accessibilityLabel={loc.close} tabIndex={-1} />
         <View style={[styles.panel, { width: screenSize.small ? "100%" : width }]}>
           <PortalHost>
             <View style={styles.header}>
@@ -94,7 +96,7 @@ export function Drawer(props: DrawerProps) {
                 <View style={styles.nav}>
                   <IconButton
                     icon="chevron-left"
-                    accessibilityLabel="Previous record"
+                    accessibilityLabel={loc.previous}
                     onPress={onPrev ?? (() => {})}
                     disabled={!onPrev}
                   />
@@ -105,13 +107,13 @@ export function Drawer(props: DrawerProps) {
                   ) : null}
                   <IconButton
                     icon="chevron-right"
-                    accessibilityLabel="Next record"
+                    accessibilityLabel={loc.next}
                     onPress={onNext ?? (() => {})}
                     disabled={!onNext}
                   />
                 </View>
               ) : null}
-              <IconButton icon="x" size="lg" accessibilityLabel="Close" onPress={handleClose} />
+              <IconButton icon="x" size="lg" accessibilityLabel={loc.close} onPress={handleClose} />
             </View>
             <View testID={testID} style={styles.body}>
               {children}

package/src/filter_chip.tsx

@@ -7,6 +7,7 @@ import { TextLink } from "./text_link";
 import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
+import { useLoticsLocale } from "./locale";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -69,7 +70,8 @@ export function selectSummary(
  * toolbar's `ColumnFilter` is this pill plus its query-condition mapping.
  */
 export function FilterChip(props: FilterChipProps) {
-  const { label, summary, onClear, clearLabel = "Clear", children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
+  const { label, summary, onClear, children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
+  const clearLabel = props.clearLabel ?? useLoticsLocale().filterChip.clear;
   const active = summary != null && (typeof summary !== "string" || summary.length > 0);
   // The clear × / Clear footer only when there's a clearable selection AND no
   // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.

package/src/locale.tsx

@@ -0,0 +1,190 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { type PaginationLabels } from "./pagination";
+import { type SortHeaderLabels } from "./sort_header";
+import { type ConfidenceLabels } from "./confidence";
+import { type RemainderMeterLabels } from "./remainder_meter";
+import { type DateRangeFilterFieldLabels } from "./date_range_filter_field";
+
+/**
+ * The kit's localizable strings, one slice per string-bearing component. A
+ * `LoticsLocale` is plain DATA (like a date-fns locale) — it carries no i18n
+ * LOGIC, so the kit stays translation-agnostic while an app supplies the pack
+ * once at its root. Each slice REUSES the component's own `*Labels` type, so
+ * adding a localizable string to a component (a new key on its `Labels`) forces
+ * BOTH packs below to fill it — a missing translation is a compile error here,
+ * never a silent English leak at a call site.
+ *
+ * Resolution order in every wired component: an explicit per-instance prop wins,
+ * else this locale (from `LoticsLocaleProvider`, default `en`), else nothing —
+ * the locale is always complete, so there is no third fallback to forget.
+ */
+export interface LoticsLocale {
+  /** `Pagination` range + page summaries and the prev/next tooltips. */
+  pagination: Required<PaginationLabels>;
+  /** `SortHeader` a11y prefix + asc/desc suffixes. */
+  sortHeader: Required<SortHeaderLabels>;
+  /** `OptionList` (and everything built on it — `Select`, `Combobox`, the
+   *  in-cell editors): the select-all/deselect-all links, the empty state, and
+   *  the `Combobox` recents header. */
+  optionList: { selectAll: string; deselectAll: string; noResults: string; recent: string };
+  /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
+   *  a call site doesn't pass a dimension-specific `clearLabel`. */
+  filterChip: { clear: string };
+  /** `Drawer`: the record prev/next + close controls (screen-reader names). */
+  drawer: { previous: string; next: string; close: string };
+  /** `Confidence`: the full level phrase ("High confidence" …). */
+  confidence: ConfidenceLabels;
+  /** `RemainderMeter`: the applied / remaining / over / exact captions. */
+  remainderMeter: Required<RemainderMeterLabels>;
+  /** `ChangeReview` (+ `ChangeReviewActions`): the review-card chrome — the
+   *  Keep/Drop verdicts, Undo, the Applied/Discarded tags, the kept-counter,
+   *  the title, and the commit-bar Accept-all / Discard. */
+  changeReview: {
+    title: string;
+    accept: string;
+    reject: string;
+    undo: string;
+    applied: string;
+    discarded: string;
+    keptCount: (kept: number, total: number) => string;
+    acceptAll: string;
+    discard: string;
+    apply: string;
+    applyKept: string;
+  };
+  /** `DateRangeFilterField` (and the `DateFilter` panel it wraps): presets,
+   *  from/to, the footer Clear/Done, the trigger placeholder, and the time-field
+   *  segment a11y names. */
+  dateRange: DateRangeFilterFieldLabels;
+}
+
+/** The platform default — English. Every component's hardcoded default lives
+ *  HERE now, so the strings are documented in one place and overridable. */
+export const en: LoticsLocale = {
+  pagination: {
+    rangeWithTotal: (start, end, total) => `${start}–${end} of ${total.toLocaleString()}`,
+    range: (start, end) => `${start}–${end}`,
+    pageWithTotal: (page, pageCount) => `Page ${page} of ${pageCount}`,
+    page: (page) => `Page ${page}`,
+    previous: "Previous",
+    next: "Next",
+  },
+  sortHeader: {
+    sortBy: (label) => `Sort by ${label}`,
+    ascending: ", ascending",
+    descending: ", descending",
+  },
+  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent" },
+  filterChip: { clear: "Clear" },
+  drawer: { previous: "Previous record", next: "Next record", close: "Close" },
+  confidence: { high: "High confidence", medium: "Medium confidence", low: "Low confidence" },
+  remainderMeter: {
+    applied: (allocated, total) => `${allocated} of ${total} applied`,
+    remaining: (remainder) => `${remainder} unapplied`,
+    over: (amount) => `Over by ${amount}`,
+    exact: "Fully applied",
+  },
+  changeReview: {
+    title: "Suggested edits",
+    accept: "Keep",
+    reject: "Drop",
+    undo: "Undo",
+    applied: "Applied",
+    discarded: "Discarded",
+    keptCount: (kept, total) => `${kept} of ${total} kept`,
+    acceptAll: "Accept all",
+    discard: "Discard",
+    apply: "Apply",
+    applyKept: "Apply kept",
+  },
+  dateRange: {
+    year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
+    today: "Today", yesterday: "Yesterday", tomorrow: "Tomorrow",
+    thisWeek: "This week", thisMonth: "This month", lastMonth: "Last month",
+    custom: "Custom", from: "From", to: "To",
+    selectDateRange: "Select date range", selectDate: "Select date",
+    clear: "Clear", done: "Done", placeholder: "All time",
+  },
+};
+
+/** Vietnamese. Maintained once here so every app (and the frontend) shares one
+ *  canonical translation — no per-app drift ("Chọn tất cả" vs "Chọn hết"). */
+export const vi: LoticsLocale = {
+  pagination: {
+    rangeWithTotal: (start, end, total) => `${start}–${end} trên ${total.toLocaleString("vi-VN")}`,
+    range: (start, end) => `${start}–${end}`,
+    pageWithTotal: (page, pageCount) => `Trang ${page} / ${pageCount}`,
+    page: (page) => `Trang ${page}`,
+    previous: "Trang trước",
+    next: "Trang sau",
+  },
+  sortHeader: {
+    sortBy: (label) => `Sắp xếp theo ${label}`,
+    ascending: " (tăng dần)",
+    descending: " (giảm dần)",
+  },
+  optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", noResults: "Không có kết quả", recent: "Gần đây" },
+  filterChip: { clear: "Xóa" },
+  drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
+  confidence: { high: "Độ tin cậy cao", medium: "Độ tin cậy trung bình", low: "Độ tin cậy thấp" },
+  remainderMeter: {
+    applied: (allocated, total) => `Đã phân bổ ${allocated}/${total}`,
+    remaining: (remainder) => `Còn ${remainder}`,
+    over: (amount) => `Vượt ${amount}`,
+    exact: "Đã phân bổ đủ",
+  },
+  changeReview: {
+    title: "Đề xuất chỉnh sửa",
+    accept: "Giữ",
+    reject: "Bỏ",
+    undo: "Hoàn tác",
+    applied: "Đã áp dụng",
+    discarded: "Đã bỏ",
+    keptCount: (kept, total) => `Giữ ${kept}/${total}`,
+    acceptAll: "Giữ tất cả",
+    discard: "Hủy",
+    apply: "Áp dụng",
+    applyKept: "Áp dụng mục đã giữ",
+  },
+  dateRange: {
+    year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH",
+    today: "Hôm nay", yesterday: "Hôm qua", tomorrow: "Ngày mai",
+    thisWeek: "Tuần này", thisMonth: "Tháng này", lastMonth: "Tháng trước",
+    custom: "Tùy chọn", from: "Từ", to: "Đến",
+    selectDateRange: "Chọn khoảng ngày", selectDate: "Chọn ngày",
+    clear: "Xóa", done: "Xong", placeholder: "Tất cả thời gian",
+  },
+};
+
+const LoticsLocaleContext = createContext<LoticsLocale>(en);
+
+interface LoticsLocaleProviderProps {
+  /** The locale pack supplying every kit string. Import a shipped pack
+   *  (`import { vi } from "@lotics/ui/locale"`) or pass your own `LoticsLocale`. */
+  locale: LoticsLocale;
+  children: ReactNode;
+}
+
+/**
+ * App-root provider that supplies localized strings to @lotics/ui primitives —
+ * the sibling of `LoticsThemeProvider`. Wrap your top-level element once and
+ * every wired component picks up the pack; no per-instance label props:
+ *
+ *     // src/main.tsx
+ *     import { vi } from "@lotics/ui/locale";
+ *     <LoticsLocaleProvider locale={vi}>
+ *       <App />
+ *     </LoticsLocaleProvider>
+ *
+ * Components read the locale via `useLoticsLocale()`. A per-instance label prop
+ * still overrides for one-offs; without a provider the English default applies,
+ * so an un-wrapped app behaves exactly as before.
+ */
+export function LoticsLocaleProvider(props: LoticsLocaleProviderProps) {
+  return <LoticsLocaleContext.Provider value={props.locale}>{props.children}</LoticsLocaleContext.Provider>;
+}
+
+/** Read the current locale. Wired primitives call this; apps use the provider. */
+export function useLoticsLocale(): LoticsLocale {
+  return useContext(LoticsLocaleContext);
+}

package/src/option_list.tsx

@@ -10,6 +10,7 @@ import { ActivityIndicator } from "./activity_indicator";
 import { TextInputField } from "./text_input_field";
 import { useScreenSize } from "./use_screen_size";
 import { useOptionList, type UseOptionListParams } from "./use_option_list";
+import { useLoticsLocale } from "./locale";
 import type { PickerOption } from "./picker";
 
 export interface OptionListProps<T extends string = string, MULTI extends boolean = false, D = unknown>
@@ -38,17 +39,11 @@ export interface OptionListProps<T extends string = string, MULTI extends boolea
 export function OptionList<T extends string, MULTI extends boolean = false, D = unknown>(
   props: OptionListProps<T, MULTI, D>,
 ) {
-  const {
-    testID,
-    renderOptionContent,
-    getOptionDescription,
-    loading = false,
-    emptyText = "No results",
-    accessibilityLabel,
-    selectAllLabel = "Select all",
-    deselectAllLabel = "Deselect all",
-    search,
-  } = props;
+  const { testID, renderOptionContent, getOptionDescription, loading = false, accessibilityLabel, search } = props;
+  const loc = useLoticsLocale().optionList;
+  const emptyText = props.emptyText ?? loc.noResults;
+  const selectAllLabel = props.selectAllLabel ?? loc.selectAll;
+  const deselectAllLabel = props.deselectAllLabel ?? loc.deselectAll;
   const list = useOptionList(props);
   const { small } = useScreenSize();
 

package/src/pagination.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { View, StyleSheet } from "react-native";
 import { IconButton } from "./icon_button";
 import { Text } from "./text";
+import { useLoticsLocale } from "./locale";
 
 /**
  * Localizable strings for `Pagination`. Every field is optional; an omitted
@@ -25,12 +26,6 @@ export interface PaginationLabels {
   next?: string;
 }
 
-const defaultRangeWithTotal = (start: number, end: number, total: number): string =>
-  `${start}–${end} of ${total.toLocaleString()}`;
-const defaultRange = (start: number, end: number): string => `${start}–${end}`;
-const defaultPageWithTotal = (page: number, pageCount: number): string => `Page ${page} of ${pageCount}`;
-const defaultPage = (page: number): string => `Page ${page}`;
-
 export interface PaginationProps {
   /** 0-indexed. */
   page: number;
@@ -59,20 +54,21 @@ export interface PaginationProps {
  */
 export function Pagination(props: PaginationProps): React.ReactNode {
   const { page, pageSize, rowCount, hasMore, total, loading, onPageChange, labels } = props;
+  const loc = useLoticsLocale().pagination;
   const start = page * pageSize + 1;
   const end = page * pageSize + rowCount;
   const showRange = !loading && rowCount > 0;
 
   const summary = showRange
     ? total !== undefined
-      ? (labels?.rangeWithTotal ?? defaultRangeWithTotal)(start, end, total)
-      : (labels?.range ?? defaultRange)(start, end)
+      ? (labels?.rangeWithTotal ?? loc.rangeWithTotal)(start, end, total)
+      : (labels?.range ?? loc.range)(start, end)
     : "";
 
   const pageLabel =
     total !== undefined
-      ? (labels?.pageWithTotal ?? defaultPageWithTotal)(page + 1, Math.max(1, Math.ceil(total / pageSize)))
-      : (labels?.page ?? defaultPage)(page + 1);
+      ? (labels?.pageWithTotal ?? loc.pageWithTotal)(page + 1, Math.max(1, Math.ceil(total / pageSize)))
+      : (labels?.page ?? loc.page)(page + 1);
 
   return (
     <View style={styles.container}>
@@ -90,14 +86,14 @@ export function Pagination(props: PaginationProps): React.ReactNode {
           color="secondary"
           onPress={() => onPageChange(Math.max(0, page - 1))}
           disabled={page === 0 || !!loading}
-          tooltip={labels?.previous ?? "Previous"}
+          tooltip={labels?.previous ?? loc.previous}
         />
         <IconButton
           icon="chevron-right"
           color="secondary"
           onPress={() => onPageChange(page + 1)}
           disabled={!hasMore || !!loading}
-          tooltip={labels?.next ?? "Next"}
+          tooltip={labels?.next ?? loc.next}
         />
       </View>
     </View>

package/src/remainder_meter.tsx

@@ -1,6 +1,7 @@
 import { StyleSheet, View, type DimensionValue } from "react-native";
 import { colors, solid } from "./colors";
 import { Text } from "./text";
+import { useLoticsLocale } from "./locale";
 
 /**
  * Override the meter's captions for localization. Each key is optional and
@@ -17,11 +18,6 @@ export interface RemainderMeterLabels {
   exact?: string;
 }
 
-const defaultApplied = (allocated: string, total: string) => `${allocated} of ${total} applied`;
-const defaultRemaining = (remainder: string) => `${remainder} unapplied`;
-const defaultOver = (amount: string) => `Over by ${amount}`;
-const DEFAULT_EXACT = "Fully applied";
-
 export interface RemainderMeterProps {
   /** The source amount being distributed — the payment, the available stock. */
   total: number;
@@ -43,20 +39,21 @@ export interface RemainderMeterProps {
  */
 export function RemainderMeter(props: RemainderMeterProps) {
   const { total, allocated, format = (n) => n.toLocaleString(), labels } = props;
+  const loc = useLoticsLocale().remainderMeter;
   const remainder = total - allocated;
   const state = remainder > 0 ? "under" : remainder < 0 ? "over" : "exact";
   const pct: DimensionValue = `${total <= 0 ? 0 : Math.min(100, (allocated / total) * 100)}%`;
   const barColor = state === "over" ? solid("red") : state === "exact" ? solid("emerald") : solid("blue");
   const right =
     state === "exact"
-      ? (labels?.exact ?? DEFAULT_EXACT)
+      ? (labels?.exact ?? loc.exact)
       : state === "over"
-        ? (labels?.over ?? defaultOver)(format(-remainder))
-        : (labels?.remaining ?? defaultRemaining)(format(remainder));
+        ? (labels?.over ?? loc.over)(format(-remainder))
+        : (labels?.remaining ?? loc.remaining)(format(remainder));
   return (
     <View style={{ gap: 8 }}>
       <View style={{ flexDirection: "row", alignItems: "baseline", gap: 8 }}>
-        <Text size="sm" color="muted" style={{ flex: 1 }}>{(labels?.applied ?? defaultApplied)(format(allocated), format(total))}</Text>
+        <Text size="sm" color="muted" style={{ flex: 1 }}>{(labels?.applied ?? loc.applied)(format(allocated), format(total))}</Text>
         <Text size="sm" weight="medium" tabular color={state === "over" ? "danger" : state === "exact" ? "success" : "default"}>
           {right}
         </Text>

package/src/sort_header.tsx

@@ -3,6 +3,7 @@ import { Text } from "./text";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
+import { useLoticsLocale } from "./locale";
 
 export type SortDir = "asc" | "desc";
 export interface SortState {
@@ -74,14 +75,11 @@ export interface SortHeaderProps {
  */
 export function SortHeader(props: SortHeaderProps) {
   const { label, sortKey, sort, onSort, align = "left", style, labels } = props;
+  const loc = useLoticsLocale().sortHeader;
   const active = sort?.key === sortKey;
   const arrow = active ? (sort.dir === "asc" ? "chevron-up" : "chevron-down") : undefined;
-  const dirText = active
-    ? sort.dir === "asc"
-      ? (labels?.ascending ?? ", ascending")
-      : (labels?.descending ?? ", descending")
-    : "";
-  const sortByLabel = (labels?.sortBy ?? ((l: string) => `Sort by ${l}`))(label);
+  const dirText = active ? (sort.dir === "asc" ? (labels?.ascending ?? loc.ascending) : (labels?.descending ?? loc.descending)) : "";
+  const sortByLabel = (labels?.sortBy ?? loc.sortBy)(label);
 
   return (
     <PressableHighlight