From 7a272066e6e03b5f3dffa540d6afee3a1e225272 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Bryxi=CC=81?= <michal.bryxi@gmail.com>
Date: Thu, 15 Oct 2026 11:04:33 +0200
Subject: [PATCH 1/2] feat(forms): translatable DatePicker, DateInput and
 Calendar labels

The date components' own text was hard-coded English: the clear button,
the calendar button ("Choose date, <label>"), and the calendar's
previous/next buttons, month select and year grid. `@labels` overrides
any of them; whatever is left out keeps today's default, so nothing
changes for existing users.

- Calendar: `previousMonth`, `nextMonth`, `month`, `year`.
- DateInput: `clear`.
- DatePicker: `clear`, `chooseDate` and the calendar's four, handed on to
  its calendar and to a `:calendar` block. `chooseDate` is a function of
  the field's `@label`, since some languages put it elsewhere in the
  sentence.

The segments' names stay `@segmentLabels`.

Closes #622

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../collections/calendar/calendar.gts         | 20 +++++
 .../collections/calendar/calendar.md          | 25 ++++++
 .../collections/calendar/header.gts           |  8 +-
 .../components/collections/calendar/types.ts  | 16 ++++
 .../collections/calendar/year-grid.gts        |  4 +-
 .../src/components/forms/date-input.md        | 24 ++++++
 .../forms/date-input/date-input.gts           | 11 ++-
 .../src/components/forms/date-input/types.ts  | 17 ++++
 .../src/components/forms/date-picker.md       | 50 ++++++++++-
 .../forms/date-picker/date-picker.gts         | 25 +++++-
 .../forms/date-picker/end-content.gts         |  9 +-
 .../src/components/forms/date-picker/types.ts | 28 ++++++
 .../components/collections/calendar-test.gts  | 50 +++++++++++
 .../components/forms/date-input-test.gts      | 36 ++++++++
 .../components/forms/date-picker-test.gts     | 86 ++++++++++++++++++-
 15 files changed, 396 insertions(+), 13 deletions(-)

diff --git a/packages/frontile/src/components/collections/calendar/calendar.gts b/packages/frontile/src/components/collections/calendar/calendar.gts
index e5683f611..63790152e 100644
--- a/packages/frontile/src/components/collections/calendar/calendar.gts
+++ b/packages/frontile/src/components/collections/calendar/calendar.gts
@@ -37,6 +37,7 @@ import {
 import type { CalendarSlots, CalendarVariants } from '@frontile/theme';
 import type {
   CalendarDay,
+  CalendarLabels,
   CalendarMode,
   CalendarMonthData,
   CalendarValue,
@@ -195,8 +196,21 @@ export interface CalendarArgs<M extends CalendarMode = 'single'> {
    * @defaultValue 'label'
    */
   captionLayout?: 'label' | 'dropdown';
+
+  /**
+   * Replaces any of the texts the calendar renders, e.g. to translate them.
+   * Anything left out keeps its English default; see `CalendarLabels`.
+   */
+  labels?: Partial<CalendarLabels>;
 }
 
+const DEFAULT_LABELS: CalendarLabels = {
+  previousMonth: 'Previous month',
+  nextMonth: 'Next month',
+  month: 'Month',
+  year: 'Year'
+};
+
 export interface CalendarSignature<M extends CalendarMode = 'single'> {
   Args: CalendarArgs<M>;
   Blocks: {
@@ -234,6 +248,10 @@ class Calendar<M extends CalendarMode = 'single'> extends Component<
     return this.args.captionLayout ?? 'label';
   }
 
+  get labels(): CalendarLabels {
+    return { ...DEFAULT_LABELS, ...this.args.labels };
+  }
+
   // The autofocus below is deferred a frame; `deferredWork` holds the
   // test-waiter token so `settled()` does not race it, and cancels cleanly on
   // teardown.
@@ -1097,6 +1115,7 @@ class Calendar<M extends CalendarMode = 'single'> extends Component<
             @months={{this.monthOptions}}
             @isYearGridOpen={{this.isYearGridOpen}}
             @onToggleYearGrid={{this.toggleYearGrid}}
+            @labels={{this.labels}}
             @classes={{this.headerClasses}}
           />
         {{/if}}
@@ -1113,6 +1132,7 @@ class Calendar<M extends CalendarMode = 'single'> extends Component<
             @currentYear={{this.visibleYear}}
             @onSelect={{this.pickYear}}
             @onDismiss={{this.dismissYearGrid}}
+            @label={{this.labels.year}}
             @classes={{this.yearGridClasses}}
           />
         {{else}}
diff --git a/packages/frontile/src/components/collections/calendar/calendar.md b/packages/frontile/src/components/collections/calendar/calendar.md
index b0cfea531..527586197 100644
--- a/packages/frontile/src/components/collections/calendar/calendar.md
+++ b/packages/frontile/src/components/collections/calendar/calendar.md
@@ -405,6 +405,31 @@ import { Calendar } from 'frontile/collections';
 <template><Calendar @locale='nl-NL' @weekStartsOn={{1}} /></template>
 ```
 
+## Labels
+
+`@locale` covers everything `Intl` can format, but the accessible names of the
+previous/next buttons, and of the month `<select>` and year grid under
+`@captionLayout="dropdown"`, are English by default. `@labels` replaces any of
+them, e.g. to translate them; anything you leave out keeps its default.
+
+```gts preview
+import { hash } from '@ember/helper';
+import { Calendar } from 'frontile/collections';
+
+<template>
+  <Calendar
+    @locale='cs-CZ'
+    @captionLayout='dropdown'
+    @labels={{hash
+      previousMonth='Předchozí měsíc'
+      nextMonth='Další měsíc'
+      month='Měsíc'
+      year='Rok'
+    }}
+  />
+</template>
+```
+
 ## Disabled and read-only
 
 `@isDisabled` blocks navigation and selection entirely. `@isReadOnly` still allows paging
diff --git a/packages/frontile/src/components/collections/calendar/header.gts b/packages/frontile/src/components/collections/calendar/header.gts
index 19ae73d22..a507ff50c 100644
--- a/packages/frontile/src/components/collections/calendar/header.gts
+++ b/packages/frontile/src/components/collections/calendar/header.gts
@@ -5,6 +5,7 @@ import {
   ChevronLeftIcon,
   ChevronRightIcon
 } from '../../../-private/icons';
+import type { CalendarLabels } from './types';
 
 export interface CalendarHeaderContext {
   month: Date;
@@ -26,6 +27,7 @@ export interface CalendarHeaderSignature {
     months: { value: number; label: string; isDisabled: boolean }[];
     isYearGridOpen: boolean;
     onToggleYearGrid: () => void;
+    labels: Pick<CalendarLabels, 'previousMonth' | 'nextMonth' | 'month'>;
     classes: {
       header: string;
       title: string;
@@ -81,7 +83,7 @@ export default class CalendarHeader extends Component<CalendarHeaderSignature> {
         class={{@classes.navButton}}
         disabled={{if @context.canGoPrevious false true}}
         data-disabled={{if @context.canGoPrevious "false" "true"}}
-        aria-label="Previous month"
+        aria-label={{@labels.previousMonth}}
         {{on "click" @context.goToPrevious}}
       ><ChevronLeftIcon /></button>
 
@@ -107,7 +109,7 @@ export default class CalendarHeader extends Component<CalendarHeaderSignature> {
 
             <select
               data-part="month-select"
-              aria-label="Month"
+              aria-label={{@labels.month}}
               class={{@classes.monthSelect}}
               {{on "change" this.onMonthSelect}}
             >
@@ -141,7 +143,7 @@ export default class CalendarHeader extends Component<CalendarHeaderSignature> {
         class={{@classes.navButton}}
         disabled={{if @context.canGoNext false true}}
         data-disabled={{if @context.canGoNext "false" "true"}}
-        aria-label="Next month"
+        aria-label={{@labels.nextMonth}}
         {{on "click" @context.goToNext}}
       ><ChevronRightIcon /></button>
     </div>
diff --git a/packages/frontile/src/components/collections/calendar/types.ts b/packages/frontile/src/components/collections/calendar/types.ts
index 89884736f..e7bda2795 100644
--- a/packages/frontile/src/components/collections/calendar/types.ts
+++ b/packages/frontile/src/components/collections/calendar/types.ts
@@ -104,3 +104,19 @@ export interface DayCellClasses {
   dayContent: string;
   indicator: string;
 }
+
+/**
+ * Every text the calendar renders itself, beyond what `Intl` produces from
+ * `@locale`. Override any of them with `@labels`, e.g. to translate them; the
+ * rest keep these English defaults.
+ */
+export interface CalendarLabels {
+  /** Accessible name of the previous-month button. */
+  previousMonth: string;
+  /** Accessible name of the next-month button. */
+  nextMonth: string;
+  /** Accessible name of the month `<select>` (`@captionLayout="dropdown"`). */
+  month: string;
+  /** Accessible name of the year grid (`@captionLayout="dropdown"`). */
+  year: string;
+}
diff --git a/packages/frontile/src/components/collections/calendar/year-grid.gts b/packages/frontile/src/components/collections/calendar/year-grid.gts
index b871467ec..671d99506 100644
--- a/packages/frontile/src/components/collections/calendar/year-grid.gts
+++ b/packages/frontile/src/components/collections/calendar/year-grid.gts
@@ -9,6 +9,8 @@ export interface YearGridSignature {
     currentYear: number;
     onSelect: (year: number) => void;
     onDismiss: () => void;
+    /** The grid's accessible name. */
+    label: string;
     classes: { yearGrid: string; yearCell: string };
   };
   Element: HTMLDivElement;
@@ -167,7 +169,7 @@ export default class YearGrid extends Component<YearGridSignature> {
          plain, non-focusable listbox role. }}
     <div
       role="listbox"
-      aria-label="Year"
+      aria-label={{@label}}
       data-part="year-grid"
       class={{@classes.yearGrid}}
       {{this.setup}}
diff --git a/packages/frontile/src/components/forms/date-input.md b/packages/frontile/src/components/forms/date-input.md
index 2bdc8d457..b0a3f6e60 100644
--- a/packages/frontile/src/components/forms/date-input.md
+++ b/packages/frontile/src/components/forms/date-input.md
@@ -279,6 +279,30 @@ const value = new Date(2026, 0, 20);
 </template>
 ```
 
+## Labels
+
+The segments' accessible names are `@segmentLabels`. The only other text the
+field renders, the clear button's accessible name, is `@labels.clear`; it
+defaults to "Clear".
+
+```gts preview
+import { hash } from '@ember/helper';
+import { DateInput } from 'frontile';
+
+const value = new Date(2026, 0, 20);
+
+<template>
+  <DateInput
+    @label='Začátek'
+    @locale='cs-CZ'
+    @defaultValue={{value}}
+    @isClearable={{true}}
+    @segmentLabels={{hash year='rok' month='měsíc' day='den'}}
+    @labels={{hash clear='Vymazat'}}
+  />
+</template>
+```
+
 ## Sizes
 
 ```gts preview
diff --git a/packages/frontile/src/components/forms/date-input/date-input.gts b/packages/frontile/src/components/forms/date-input/date-input.gts
index f8d74d1a5..84666da2a 100644
--- a/packages/frontile/src/components/forms/date-input/date-input.gts
+++ b/packages/frontile/src/components/forms/date-input/date-input.gts
@@ -22,9 +22,14 @@ import type {
   Part,
   DateInputArgs,
   DateInputClasses,
+  DateInputLabels,
   TimeOptions
 } from './types';
 
+const DEFAULT_LABELS: DateInputLabels = {
+  clear: 'Clear'
+};
+
 interface DateInputSignature {
   Args: DateInputArgs;
   Element: HTMLDivElement;
@@ -213,6 +218,10 @@ class DateInput extends Component<DateInputSignature> {
     this.args.onBlur?.();
   };
 
+  get labels(): DateInputLabels {
+    return { ...DEFAULT_LABELS, ...this.args.labels };
+  }
+
   /**
    * A disabled or read-only field never offers it: it carries no disabled
    * state of its own and would be a live button clearing a field the user may
@@ -301,7 +310,7 @@ class DateInput extends Component<DateInputSignature> {
               class={{this.classes.endContent class=@classes.endContent}}
             >
               <CloseButton
-                @title="Clear"
+                @title={{this.labels.clear}}
                 @variant="soft"
                 @size="xs"
                 @class={{this.classes.clearButton class=@classes.clearButton}}
diff --git a/packages/frontile/src/components/forms/date-input/types.ts b/packages/frontile/src/components/forms/date-input/types.ts
index 2694904b3..58bdd1019 100644
--- a/packages/frontile/src/components/forms/date-input/types.ts
+++ b/packages/frontile/src/components/forms/date-input/types.ts
@@ -95,6 +95,16 @@ interface LiteralPart {
 
 type Part = Segment | LiteralPart;
 
+/**
+ * Every text the field renders itself. Override any of them with `@labels`,
+ * e.g. to translate them; the rest keep these English defaults. The
+ * segments' names are `@segmentLabels`.
+ */
+interface DateInputLabels {
+  /** Accessible name of the clear button (`@isClearable`). */
+  clear: string;
+}
+
 interface DateInputArgs extends FormControlSharedArgs {
   /** The unique identifier for the control. */
   id?: string;
@@ -201,11 +211,18 @@ interface DateInputArgs extends FormControlSharedArgs {
    */
   segmentLabels?: Partial<Record<SegmentType, string>>;
 
+  /**
+   * Replaces any of the texts the field renders, e.g. to translate them.
+   * Anything left out keeps its English default; see `DateInputLabels`.
+   */
+  labels?: Partial<DateInputLabels>;
+
   /** Per-slot class overrides. */
   classes?: SlotsToClasses<DateInputSlots>;
 }
 
 export type {
+  DateInputLabels,
   SegmentType,
   Granularity,
   HourCycle,
diff --git a/packages/frontile/src/components/forms/date-picker.md b/packages/frontile/src/components/forms/date-picker.md
index b25b5432b..c9f9ccef9 100644
--- a/packages/frontile/src/components/forms/date-picker.md
+++ b/packages/frontile/src/components/forms/date-picker.md
@@ -441,6 +441,52 @@ const defaultValue = new Date(2026, 0, 20);
 </template>
 ```
 
+## Labels
+
+Every text the picker renders itself is English by default: the clear and
+calendar buttons' accessible names, and those of its calendar's controls.
+`@labels` replaces any of them, e.g. to translate them; anything you leave out
+keeps its default. The calendar's are handed on to it, including to a calendar
+you render from the `:calendar` block. `chooseDate` is a function of the
+field's `@label`, since some languages put it elsewhere in the sentence. The
+segments' names are `@segmentLabels`.
+
+```gts preview
+import { hash } from '@ember/helper';
+import { DatePicker } from 'frontile';
+
+const defaultValue = new Date(2026, 0, 20, 9, 30);
+const chooseDate = (label?: string) =>
+  label ? `Vybrat datum, ${label}` : 'Vybrat datum';
+
+<template>
+  <DatePicker
+    @label='Začátek'
+    @locale='cs-CZ'
+    @granularity='minute'
+    @hourCycle={{24}}
+    @captionLayout='dropdown'
+    @defaultValue={{defaultValue}}
+    @isClearable={{true}}
+    @segmentLabels={{hash
+      year='rok'
+      month='měsíc'
+      day='den'
+      hour='hodina'
+      minute='minuta'
+    }}
+    @labels={{hash
+      clear='Vymazat'
+      chooseDate=chooseDate
+      previousMonth='Předchozí měsíc'
+      nextMonth='Další měsíc'
+      month='Měsíc'
+      year='Rok'
+    }}
+  />
+</template>
+```
+
 ## Forms
 
 Inside a `<Form>`, a `DatePicker` given `@name` submits one field: the wire value is the same
@@ -535,11 +581,11 @@ and `calendarButton`.
 | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Segment         | `role="spinbutton"` with `aria-label` (`month`, `day`, `year`, overridable through `@segmentLabels`), `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` — which is what makes a month announce as "January" rather than "1". Carries the field's `aria-invalid` and `aria-readonly`. |
 | Segment group   | `role="group"`, named by `@label` and described by `@description` and any feedback. In range mode there are two, named `"<label> start"` and `"<label> end"`.                                                                                                                                             |
-| Calendar button | A `<button>` labelled `"Choose date, <label>"`, carrying the `aria-haspopup`, `aria-expanded` and `aria-controls` the popover trigger applies.                                                                                                                                                            |
+| Calendar button | A `<button>` labelled `"Choose date, <label>"` (`@labels.chooseDate`), carrying the `aria-haspopup`, `aria-expanded` and `aria-controls` the popover trigger applies.                                                                                                                                     |
 | Trigger         | Under `@isEditable={{false}}`, a `<button>` carrying the same popover trigger attributes. When a `:value` block is supplied, it also carries an explicit `aria-label` composed from `@label` and the formatted value, since the block's content may not be readable text on its own.                      |
 | Popover content | `role="dialog"`, labeled by `@label`.                                                                                                                                                                                                                                                                     |
 | Calendar grid   | Labeled by the field's own id, so the default calendar is always labelled. A consumer rendering their own calendar from the `:calendar` block must pass `@id` to `DatePicker` for the grid to be labelled — the block's `labelledBy` reflects `@id`, not the id `FormControl` would otherwise generate.   |
-| Clear button    | Announced as "Clear".                                                                                                                                                                                                                                                                                     |
+| Clear button    | Announced as "Clear" (`@labels.clear`).                                                                                                                                                                                                                                                                   |
 
 The segments take the same keys as [DateInput](./date-input#accessibility), and every one
 of them is a tab stop — three for a single field, six for a range.
diff --git a/packages/frontile/src/components/forms/date-picker/date-picker.gts b/packages/frontile/src/components/forms/date-picker/date-picker.gts
index c288e8a79..9e768a351 100644
--- a/packages/frontile/src/components/forms/date-picker/date-picker.gts
+++ b/packages/frontile/src/components/forms/date-picker/date-picker.gts
@@ -39,11 +39,21 @@ import type {
 import type { Part, TimeOptions } from '../date-input/types';
 import type {
   DatePickerArgs,
+  DatePickerLabels,
   DatePickerValueBlockArg,
   DatePickerCalendarArgs,
   DatePickerFooterArg
 } from './types';
 
+/**
+ * The picker's own texts. The calendar's are left to `Calendar`, which owns
+ * their defaults: `@labels` is handed to it as it is.
+ */
+const DEFAULT_LABELS: Pick<DatePickerLabels, 'clear' | 'chooseDate'> = {
+  clear: 'Clear',
+  chooseDate: (label) => (label ? `Choose date, ${label}` : 'Choose date')
+};
+
 interface DatePickerSignature<M extends CalendarMode = 'single'> {
   Args: DatePickerArgs<M>;
   Blocks: {
@@ -203,6 +213,16 @@ class DatePicker<M extends CalendarMode = 'single'> extends Component<
     return (this.args as { mode?: M }).mode ?? ('single' as M);
   }
 
+  get clearLabel(): string {
+    return this.args.labels?.clear ?? DEFAULT_LABELS.clear;
+  }
+
+  get calendarButtonLabel(): string {
+    return (this.args.labels?.chooseDate ?? DEFAULT_LABELS.chooseDate)(
+      this.args.label
+    );
+  }
+
   get locale(): string {
     return this.args.locale ?? navigator.language;
   }
@@ -739,6 +759,7 @@ class DatePicker<M extends CalendarMode = 'single'> extends Component<
       isDateUnavailable: this.args.isDateUnavailable,
       visibleMonths: this.args.visibleMonths,
       captionLayout: this.args.captionLayout,
+      labels: this.args.labels,
       labelledBy: this.args.id,
       autofocus: true
     };
@@ -923,7 +944,8 @@ class DatePicker<M extends CalendarMode = 'single'> extends Component<
               @onClear={{this.clear}}
               @isEditable={{this.isSegmented}}
               @trigger={{p.trigger}}
-              @label={{@label}}
+              @calendarButtonLabel={{this.calendarButtonLabel}}
+              @clearLabel={{this.clearLabel}}
               @isDisabled={{@isDisabled}}
             />
           </div>
@@ -965,6 +987,7 @@ class DatePicker<M extends CalendarMode = 'single'> extends Component<
                 @isDateUnavailable={{@isDateUnavailable}}
                 @visibleMonths={{@visibleMonths}}
                 @captionLayout={{@captionLayout}}
+                @labels={{@labels}}
                 @fixedWeeks={{@fixedWeeks}}
                 @showOutsideDays={{@showOutsideDays}}
                 @isReadOnly={{@isReadOnly}}
diff --git a/packages/frontile/src/components/forms/date-picker/end-content.gts b/packages/frontile/src/components/forms/date-picker/end-content.gts
index b6183d393..4793d0b0f 100644
--- a/packages/frontile/src/components/forms/date-picker/end-content.gts
+++ b/packages/frontile/src/components/forms/date-picker/end-content.gts
@@ -1,5 +1,4 @@
 import type { TOC } from '@ember/component/template-only';
-import { concat } from '@ember/helper';
 import type { ModifierLike } from '@glint/template';
 import type { SlotsToClasses, DatePickerSlots } from '@frontile/theme';
 import type { DatePickerClasses } from './types';
@@ -29,7 +28,9 @@ interface DatePickerEndContentSignature {
     trigger: ModifierLike<{ Element: HTMLElement }>;
 
     /** Names the calendar button, which has no text of its own. */
-    label?: string;
+    calendarButtonLabel: string;
+    /** Names the clear button. */
+    clearLabel: string;
     isDisabled?: boolean;
 
     /**
@@ -75,7 +76,7 @@ const DatePickerEndContent: TOC<DatePickerEndContentSignature> = <template>
   >
     {{#if @isClearable}}
       <CloseButton
-        @title="Clear"
+        @title={{@clearLabel}}
         @variant="soft"
         @size="xs"
         @class={{@classes.clearButton class=@userClasses.clearButton}}
@@ -89,7 +90,7 @@ const DatePickerEndContent: TOC<DatePickerEndContentSignature> = <template>
         type="button"
         data-part="calendar-button"
         aria-haspopup="dialog"
-        aria-label={{if @label (concat "Choose date, " @label) "Choose date"}}
+        aria-label={{@calendarButtonLabel}}
         disabled={{@isDisabled}}
         class={{@classes.calendarButton class=@userClasses.calendarButton}}
         {{@trigger}}
diff --git a/packages/frontile/src/components/forms/date-picker/types.ts b/packages/frontile/src/components/forms/date-picker/types.ts
index 9f4e37f28..2f96e90dd 100644
--- a/packages/frontile/src/components/forms/date-picker/types.ts
+++ b/packages/frontile/src/components/forms/date-picker/types.ts
@@ -10,6 +10,7 @@ import type {
 } from '../../overlays/popover';
 import type { CalendarArgs } from '../../collections/calendar/calendar';
 import type {
+  CalendarLabels,
   CalendarMode,
   CalendarValue,
   DateRange,
@@ -19,6 +20,24 @@ import type { FormControlSharedArgs } from '../form-control';
 import type { DatePickerInput, DatePickerRangeInput } from './value';
 import type { Granularity, SegmentType } from '../date-input/types';
 
+/**
+ * Every text the picker renders itself, its calendar's included. Override any
+ * of them with `@labels`, e.g. to translate them; the rest keep their English
+ * defaults. The segments' names are `@segmentLabels`.
+ */
+interface DatePickerLabels extends CalendarLabels {
+  /** Accessible name of the clear button (`@isClearable`). */
+  clear: string;
+  /**
+   * Accessible name of the calendar button on a segmented field, given the
+   * field's `@label` when it has one. A function, because some languages put
+   * the label elsewhere in the sentence.
+   *
+   * @defaultValue (label) => label ? `Choose date, ${label}` : 'Choose date'
+   */
+  chooseDate: (label: string | undefined) => string;
+}
+
 interface BaseDatePickerArgs
   extends
     Pick<
@@ -160,6 +179,13 @@ interface BaseDatePickerArgs
   /** Fires when focus leaves the trigger *and* the popover. */
   onBlur?: () => void;
 
+  /**
+   * Replaces any of the texts the picker and its calendar render, e.g. to
+   * translate them. Anything left out keeps its English default; see
+   * `DatePickerLabels`.
+   */
+  labels?: Partial<DatePickerLabels>;
+
   classes?: SlotsToClasses<DatePickerSlots>;
 }
 
@@ -254,6 +280,7 @@ interface DatePickerCalendarArgs<M extends CalendarMode = 'single'> {
   isDateUnavailable?: (date: Date) => boolean;
   visibleMonths?: number;
   captionLayout?: 'label' | 'dropdown';
+  labels?: Partial<CalendarLabels>;
   labelledBy?: string;
   autofocus: boolean;
 }
@@ -270,6 +297,7 @@ interface DatePickerFooterArg<M extends CalendarMode = 'single'> {
 
 export type {
   DatePickerArgs,
+  DatePickerLabels,
   SingleDatePickerArgs,
   RangeDatePickerArgs,
   DatePickerValueBlockArg,
diff --git a/test-app/tests/integration/components/collections/calendar-test.gts b/test-app/tests/integration/components/collections/calendar-test.gts
index d1e46a6e7..b7448e5be 100644
--- a/test-app/tests/integration/components/collections/calendar-test.gts
+++ b/test-app/tests/integration/components/collections/calendar-test.gts
@@ -11,6 +11,7 @@ import {
   triggerKeyEvent,
   triggerEvent
 } from '@ember/test-helpers';
+import { hash } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { cell } from 'ember-resources';
 import { Calendar } from 'frontile';
@@ -1598,6 +1599,55 @@ module(
         .doesNotExist('the plain label is replaced');
     });
 
+    test('@labels translates the texts the calendar renders', async function (assert) {
+      await render(
+        <template>
+          <Calendar
+            @defaultMonth={{sep2026}}
+            @locale="cs-CZ"
+            @captionLayout="dropdown"
+            @labels={{hash
+              previousMonth="Předchozí měsíc"
+              nextMonth="Další měsíc"
+              month="Měsíc"
+              year="Rok"
+            }}
+          />
+        </template>
+      );
+
+      assert
+        .dom('[data-part="nav-button"]:first-child')
+        .hasAria('label', 'Předchozí měsíc');
+      assert
+        .dom('[data-part="nav-button"]:last-child')
+        .hasAria('label', 'Další měsíc');
+      assert.dom('[data-part="month-select"]').hasAria('label', 'Měsíc');
+
+      await click('[data-part="year-trigger"]');
+      assert.dom('[data-part="year-grid"]').hasAria('label', 'Rok');
+    });
+
+    test('@labels left out keep their English defaults', async function (assert) {
+      await render(
+        <template>
+          <Calendar
+            @defaultMonth={{sep2026}}
+            @locale="en-US"
+            @captionLayout="dropdown"
+            @labels={{hash month="Měsíc"}}
+          />
+        </template>
+      );
+
+      assert.dom('[data-part="month-select"]').hasAria('label', 'Měsíc');
+      assert.dom('[aria-label="Previous month"]').exists();
+      assert.dom('[aria-label="Next month"]').exists();
+
+      await click('[data-part="year-trigger"]');
+      assert.dom('[data-part="year-grid"]').hasAria('label', 'Year');
+    });
+
     test('choosing a month from the dropdown navigates', async function (assert) {
       await render(
         <template>
diff --git a/test-app/tests/integration/components/forms/date-input-test.gts b/test-app/tests/integration/components/forms/date-input-test.gts
index 473e6580d..cdf0e2b3a 100644
--- a/test-app/tests/integration/components/forms/date-input-test.gts
+++ b/test-app/tests/integration/components/forms/date-input-test.gts
@@ -10,6 +10,7 @@ import {
   fillIn,
   triggerKeyEvent
 } from '@ember/test-helpers';
+import { hash } from '@ember/helper';
 import { cell } from 'ember-resources';
 import { DateInput, DatePicker, Form } from 'frontile';
 import { fillDate } from 'frontile/test-support';
@@ -900,6 +901,41 @@ module('Integration | Component | DateInput | forms', function (hooks) {
     assert.dom('[data-part="clear-button"]').doesNotExist();
   });
 
+  test('@labels.clear names the clear button', async function (assert) {
+    const value = new Date(2026, 0, 20);
+
+    await render(
+      <template>
+        <DateInput
+          @label="Datum"
+          @locale="cs-CZ"
+          @value={{value}}
+          @isClearable={{true}}
+          @labels={{hash clear="Vymazat"}}
+        />
+      </template>
+    );
+
+    assert.dom('[data-part="clear-button"]').hasText('Vymazat');
+  });
+
+  test('the clear button is named "Clear" by default', async function (assert) {
+    const value = new Date(2026, 0, 20);
+
+    await render(
+      <template>
+        <DateInput
+          @label="Date"
+          @locale="en-US"
+          @value={{value}}
+          @isClearable={{true}}
+        />
+      </template>
+    );
+
+    assert.dom('[data-part="clear-button"]').hasText('Clear');
+  });
+
   test('marks itself invalid outside @minValue and @maxValue', async function (assert) {
     const min = new Date(2026, 0, 10);
 
diff --git a/test-app/tests/integration/components/forms/date-picker-test.gts b/test-app/tests/integration/components/forms/date-picker-test.gts
index cd522be1a..0731f2f8a 100644
--- a/test-app/tests/integration/components/forms/date-picker-test.gts
+++ b/test-app/tests/integration/components/forms/date-picker-test.gts
@@ -12,7 +12,7 @@ import {
 } from '@ember/test-helpers';
 import { cell } from 'ember-resources';
 import { trackDeprecations } from '../../../helpers/deprecations';
-import { fn } from '@ember/helper';
+import { fn, hash } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { DatePicker, Form } from 'frontile';
 import { fillDate, fillDateRange } from 'frontile/test-support';
@@ -654,6 +654,90 @@ module(
         .doesNotExist('the default calendar is replaced, not supplemented');
     });
 
+    test('@labels translates the picker and its calendar', async function (assert) {
+      const chooseDate = (label?: string) =>
+        label ? `Vybrat datum, ${label}` : 'Vybrat datum';
+
+      await render(
+        <template>
+          <DatePicker
+            @label="Začátek"
+            @defaultValue={{jan20}}
+            @locale="cs-CZ"
+            @isClearable={{true}}
+            @captionLayout="dropdown"
+            @labels={{hash
+              clear="Vymazat"
+              chooseDate=chooseDate
+              previousMonth="Předchozí měsíc"
+              nextMonth="Další měsíc"
+              month="Měsíc"
+              year="Rok"
+            }}
+          />
+        </template>
+      );
+
+      assert.dom('[data-part="clear-button"]').hasText('Vymazat');
+      assert
+        .dom('[data-part="calendar-button"]')
+        .hasAria('label', 'Vybrat datum, Začátek');
+
+      await click('[data-part="calendar-button"]');
+
+      assert
+        .dom('[data-part="nav-button"]:first-child')
+        .hasAria('label', 'Předchozí měsíc');
+      assert
+        .dom('[data-part="nav-button"]:last-child')
+        .hasAria('label', 'Další měsíc');
+      assert.dom('[data-part="month-select"]').hasAria('label', 'Měsíc');
+    });
+
+    test('without @labels the texts keep their English defaults', async function (assert) {
+      await render(
+        <template>
+          <DatePicker
+            @label="Start"
+            @defaultValue={{jan20}}
+            @locale="en-US"
+            @isClearable={{true}}
+          />
+        </template>
+      );
+
+      assert.dom('[data-part="clear-button"]').hasText('Clear');
+      assert
+        .dom('[data-part="calendar-button"]')
+        .hasAria('label', 'Choose date, Start');
+
+      await click('[data-part="calendar-button"]');
+
+      assert.dom('[aria-label="Previous month"]').exists();
+      assert.dom('[aria-label="Next month"]').exists();
+    });
+
+    test('the calendar block receives @labels', async function (assert) {
+      await render(
+        <template>
+          <DatePicker
+            @label="Start"
+            @defaultValue={{jan20}}
+            @locale="en-US"
+            @labels={{hash month="Měsíc"}}
+          >
+            <:calendar as |args|>
+              <div data-test-custom>{{args.labels.month}}</div>
+            </:calendar>
+          </DatePicker>
+        </template>
+      );
+
+      await click('[data-part="calendar-button"]');
+
+      assert.dom('[data-test-custom]').hasText('Měsíc');
+    });
+
     test('the value block owns the trigger content and names the button', async function (assert) {
       await render(
         <template>

From 3b60072d83b0ac92500b0c4e3013b8fd0d4807a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20Bryxi=CC=81?= <michal.bryxi@gmail.com>
Date: Thu, 15 Oct 2026 11:19:48 +0200
Subject: [PATCH 2/2] docs(forms): collapse the DatePicker labels demo

It is 33 lines, over the 30-line limit the site's code-block policy test
enforces for preview fences.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/frontile/src/components/forms/date-picker.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/frontile/src/components/forms/date-picker.md b/packages/frontile/src/components/forms/date-picker.md
index c9f9ccef9..33625204f 100644
--- a/packages/frontile/src/components/forms/date-picker.md
+++ b/packages/frontile/src/components/forms/date-picker.md
@@ -451,7 +451,7 @@ you render from the `:calendar` block. `chooseDate` is a function of the
 field's `@label`, since some languages put it elsewhere in the sentence. The
 segments' names are `@segmentLabels`.
 
-```gts preview
+```gts preview collapsible
 import { hash } from '@ember/helper';
 import { DatePicker } from 'frontile';