sh-ui-cli 0.52.3 → 0.55.0

package/data/registry/react/components/calendar/index.tsx

@@ -12,8 +12,8 @@ import "./styles.css";
 
 /* ───────── Helpers ───────── */
 
-
-const DEFAULT_WEEKDAYS_KO = ["일", "월", "화", "수", "목", "금", "토"] as const;
+/** 미지정 시의 기본 로케일. 기존 동작(한국어) 보존. */
+export const DEFAULT_LOCALE = "ko-KR";
 
 const isSameDay = (a: Date, b: Date) =>
   a.getFullYear() === b.getFullYear() &&
@@ -32,8 +32,68 @@ const addMonths = (d: Date, n: number) =>
 const formatIsoDate = (d: Date) =>
   `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 
-const defaultMonthLabel = (year: number, month: number) =>
-  `${year}년 ${month + 1}월`;
+/** Intl 기반 short weekday 라벨, Sunday-first 7개. */
+function deriveWeekdayLabels(locale: string): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: "short" });
+  // 2017-01-01 은 일요일 — 안전한 기준점.
+  return Array.from({ length: 7 }, (_, i) =>
+    fmt.format(new Date(2017, 0, 1 + i)),
+  );
+}
+
+function deriveMonthLabel(locale: string) {
+  const fmt = new Intl.DateTimeFormat(locale, { year: "numeric", month: "long" });
+  return (year: number, month: number) => fmt.format(new Date(year, month, 1));
+}
+
+function deriveYearLabel(locale: string) {
+  const fmt = new Intl.DateTimeFormat(locale, { year: "numeric" });
+  return (y: number) => fmt.format(new Date(y, 0, 1));
+}
+
+function deriveMonthSelectLabel(locale: string) {
+  const fmt = new Intl.DateTimeFormat(locale, { month: "long" });
+  return (m: number) => fmt.format(new Date(2017, m, 1));
+}
+
+/** Calendar 의 비-날짜 텍스트(aria-label 등). 일부만 override 가능. */
+export interface CalendarMessages {
+  /** 1년 이전 버튼 aria-label. */
+  prevYear?: string;
+  /** 1년 다음 버튼 aria-label. */
+  nextYear?: string;
+  /** 1개월 이전 버튼 aria-label. */
+  prevMonth?: string;
+  /** 1개월 다음 버튼 aria-label. */
+  nextMonth?: string;
+  /** 연도 select aria-label. */
+  yearSelectLabel?: string;
+  /** 월 select aria-label. */
+  monthSelectLabel?: string;
+}
+
+const MESSAGES_KO: Required<CalendarMessages> = {
+  prevYear: "이전 해",
+  nextYear: "다음 해",
+  prevMonth: "이전 달",
+  nextMonth: "다음 달",
+  yearSelectLabel: "연도",
+  monthSelectLabel: "월",
+};
+
+const MESSAGES_EN: Required<CalendarMessages> = {
+  prevYear: "Previous year",
+  nextYear: "Next year",
+  prevMonth: "Previous month",
+  nextMonth: "Next month",
+  yearSelectLabel: "Year",
+  monthSelectLabel: "Month",
+};
+
+function defaultMessagesFor(locale: string): Required<CalendarMessages> {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? MESSAGES_KO : MESSAGES_EN;
+}
 
 function getDaysGrid(year: number, month: number, weekStartsOn: 0 | 1) {
   const first = new Date(year, month, 1);
@@ -94,10 +154,22 @@ interface CalendarCommonProps {
   showOutsideDays?: boolean;
   /** 주의 시작 요일. 0=일, 1=월. @default 0 */
   weekStartsOn?: 0 | 1;
-  /** 요일 라벨 (Sunday-first 7개). */
+  /** 요일 라벨 (Sunday-first 7개). 미지정 시 `locale` 기반 자동 생성. */
   weekdayLabels?: readonly string[];
-  /** 월 헤더 그룹의 aria-label 포맷. @default "{year}년 {month+1}월" */
+  /** 월 헤더 그룹의 aria-label 포맷. 미지정 시 `locale` 기반 자동 생성. */
   formatMonthLabel?: (year: number, month: number) => string;
+  /**
+   * BCP47 로케일 (예: `"en-US"`, `"ja-JP"`, `"ko-KR"`). 요일·월·연도 라벨이 `Intl.DateTimeFormat` 으로
+   * 자동 생성된다. 개별 포맷터(`weekdayLabels`/`formatMonthLabel`/`CalendarYearSelect.formatYear` 등) 가
+   * 우선되고, 미지정 항목만 이 로케일에서 파생.
+   * @default "ko-KR"
+   */
+  locale?: string;
+  /**
+   * Nav 버튼/select 의 aria-label 등 비-날짜 텍스트 override. 미지정 시 `locale` 의 언어 코드(`ko`/`en`)
+   * 기반 기본값. 다른 언어를 쓸 땐 해당 언어 문자열을 직접 넘긴다.
+   */
+  messages?: CalendarMessages;
   /** 연도 dropdown 시작 연도. */
   fromYear?: number;
   /** 연도 dropdown 끝 연도. */
@@ -195,6 +267,11 @@ interface CalendarContextValue {
   weekdayLabels: string[];
   showOutsideDays: boolean;
   formatMonthLabel: (year: number, month: number) => string;
+  /** YearSelect 가 자체 `formatYear` 를 받지 않을 때 사용할 로케일 기본값. */
+  defaultFormatYear: (y: number) => string;
+  /** MonthSelect 가 자체 `formatMonth` 를 받지 않을 때 사용할 로케일 기본값. */
+  defaultFormatMonth: (m: number) => string;
+  messages: Required<CalendarMessages>;
   ariaLabel?: string;
 
   isSelected: (date: Date) => boolean;
@@ -240,7 +317,9 @@ export function Calendar(props: CalendarProps) {
     showOutsideDays = true,
     weekStartsOn = 0,
     weekdayLabels: weekdayLabelsProp,
-    formatMonthLabel = defaultMonthLabel,
+    formatMonthLabel: formatMonthLabelProp,
+    locale = DEFAULT_LOCALE,
+    messages: messagesProp,
     fromYear,
     toYear,
     className,
@@ -304,11 +383,26 @@ export function Calendar(props: CalendarProps) {
     return new Date();
   });
 
+  /* locale-derived defaults */
+  const localeWeekdays = React.useMemo(() => deriveWeekdayLabels(locale), [locale]);
+  const localeMonthLabel = React.useMemo(() => deriveMonthLabel(locale), [locale]);
+  const localeYearLabel = React.useMemo(() => deriveYearLabel(locale), [locale]);
+  const localeMonthSelectLabel = React.useMemo(
+    () => deriveMonthSelectLabel(locale),
+    [locale],
+  );
+  const resolvedMessages = React.useMemo<Required<CalendarMessages>>(
+    () => ({ ...defaultMessagesFor(locale), ...messagesProp }),
+    [locale, messagesProp],
+  );
+
   /* weekday labels */
   const weekdayLabels = React.useMemo(() => {
-    const base = weekdayLabelsProp ?? DEFAULT_WEEKDAYS_KO;
+    const base = weekdayLabelsProp ?? localeWeekdays;
     return rotateWeekdays(base, weekStartsOn);
-  }, [weekdayLabelsProp, weekStartsOn]);
+  }, [weekdayLabelsProp, localeWeekdays, weekStartsOn]);
+
+  const formatMonthLabel = formatMonthLabelProp ?? localeMonthLabel;
 
   /* year options */
   const nowYear = new Date().getFullYear();
@@ -490,6 +584,9 @@ export function Calendar(props: CalendarProps) {
     weekdayLabels,
     showOutsideDays,
     formatMonthLabel,
+    defaultFormatYear: localeYearLabel,
+    defaultFormatMonth: localeMonthSelectLabel,
+    messages: resolvedMessages,
     ariaLabel,
     isSelected: isDateSelected,
     isInRange: getRangeState,
@@ -562,7 +659,7 @@ export interface CalendarNavButtonProps
 function makeNavButton(
   displayName: string,
   defaultIcon: React.ReactNode,
-  defaultLabel: string,
+  resolveDefaultLabel: (ctx: CalendarContextValue) => string,
   resolveHandler: (ctx: CalendarContextValue) => () => void,
 ) {
   const Component = React.forwardRef<HTMLButtonElement, CalendarNavButtonProps>(
@@ -573,7 +670,7 @@ function makeNavButton(
           ref={ref}
           type="button"
           className={cn("sh-ui-calendar__nav", className)}
-          aria-label={ariaLabel ?? defaultLabel}
+          aria-label={ariaLabel ?? resolveDefaultLabel(ctx)}
           onClick={(e) => {
             resolveHandler(ctx)();
             onClick?.(e);
@@ -593,7 +690,7 @@ function makeNavButton(
 export const CalendarPrevYearButton = makeNavButton(
   "CalendarPrevYearButton",
   <ChevronDoubleLeftIcon />,
-  "이전 해",
+  (ctx) => ctx.messages.prevYear,
   (ctx) => ctx.prevYear,
 );
 
@@ -601,7 +698,7 @@ export const CalendarPrevYearButton = makeNavButton(
 export const CalendarNextYearButton = makeNavButton(
   "CalendarNextYearButton",
   <ChevronDoubleRightIcon />,
-  "다음 해",
+  (ctx) => ctx.messages.nextYear,
   (ctx) => ctx.nextYear,
 );
 
@@ -609,7 +706,7 @@ export const CalendarNextYearButton = makeNavButton(
 export const CalendarPrevMonthButton = makeNavButton(
   "CalendarPrevMonthButton",
   <ChevronLeftIcon />,
-  "이전 달",
+  (ctx) => ctx.messages.prevMonth,
   (ctx) => ctx.prevMonth,
 );
 
@@ -617,7 +714,7 @@ export const CalendarPrevMonthButton = makeNavButton(
 export const CalendarNextMonthButton = makeNavButton(
   "CalendarNextMonthButton",
   <ChevronRightIcon />,
-  "다음 달",
+  (ctx) => ctx.messages.nextMonth,
   (ctx) => ctx.nextMonth,
 );
 
@@ -626,16 +723,17 @@ export const CalendarNextMonthButton = makeNavButton(
 export interface CalendarYearSelectProps {
   /** select trigger 의 className. */
   className?: string;
-  /** label 표시 포맷. @default "{year}년" */
+  /** label 표시 포맷. 미지정 시 Calendar `locale` 기반 자동 생성. */
   formatYear?: (year: number) => string;
 }
 
 /** 연도 dropdown. sh-ui Select 로 구현. */
 export function CalendarYearSelect({
   className,
-  formatYear = (y) => `${y}년`,
+  formatYear,
 }: CalendarYearSelectProps) {
   const ctx = useCalendarContext("CalendarYearSelect");
+  const resolvedFormat = formatYear ?? ctx.defaultFormatYear;
   const year = ctx.visibleMonth.getFullYear();
   const items = ctx.yearOptions.includes(year)
     ? ctx.yearOptions
@@ -648,14 +746,14 @@ export function CalendarYearSelect({
     >
       <SelectTrigger
         className={cn("sh-ui-calendar__select-trigger", className)}
-        aria-label="연도"
+        aria-label={ctx.messages.yearSelectLabel}
       >
-        <span className="sh-ui-calendar__select-value">{formatYear(year)}</span>
+        <span className="sh-ui-calendar__select-value">{resolvedFormat(year)}</span>
       </SelectTrigger>
       <SelectContent className="sh-ui-calendar__select-popup">
         {items.map((y) => (
           <SelectItem key={y} value={String(y)}>
-            {formatYear(y)}
+            {resolvedFormat(y)}
           </SelectItem>
         ))}
       </SelectContent>
@@ -665,16 +763,17 @@ export function CalendarYearSelect({
 
 export interface CalendarMonthSelectProps {
   className?: string;
-  /** label 표시 포맷. @default "{month+1}월" */
+  /** label 표시 포맷. 미지정 시 Calendar `locale` 기반 자동 생성. */
   formatMonth?: (month: number) => string;
 }
 
 /** 월 dropdown. */
 export function CalendarMonthSelect({
   className,
-  formatMonth = (m) => `${m + 1}월`,
+  formatMonth,
 }: CalendarMonthSelectProps) {
   const ctx = useCalendarContext("CalendarMonthSelect");
+  const resolvedFormat = formatMonth ?? ctx.defaultFormatMonth;
   const month = ctx.visibleMonth.getMonth();
   return (
     <Select
@@ -683,14 +782,14 @@ export function CalendarMonthSelect({
     >
       <SelectTrigger
         className={cn("sh-ui-calendar__select-trigger", className)}
-        aria-label="월"
+        aria-label={ctx.messages.monthSelectLabel}
       >
-        <span className="sh-ui-calendar__select-value">{formatMonth(month)}</span>
+        <span className="sh-ui-calendar__select-value">{resolvedFormat(month)}</span>
       </SelectTrigger>
       <SelectContent className="sh-ui-calendar__select-popup">
         {Array.from({ length: 12 }, (_, m) => (
           <SelectItem key={m} value={String(m)}>
-            {formatMonth(m)}
+            {resolvedFormat(m)}
           </SelectItem>
         ))}
       </SelectContent>

package/data/registry/react/components/date-picker/index.module.tsx

@@ -2,7 +2,7 @@
 
 import * as React from "react";
 import { Popover as BasePopover } from "@base-ui/react/popover";
-import { Calendar, type DateRange } from "../calendar";
+import { Calendar, DEFAULT_LOCALE, type CalendarMessages, type DateRange } from "../calendar";
 import styles from "./styles.module.css";
 
 import { cn } from "@SH_UI_UTILS@";
@@ -17,6 +17,15 @@ const formatDefault = (d: Date) =>
 const startOfMonth = (d: Date) =>
   new Date(d.getFullYear(), d.getMonth(), 1);
 
+function defaultDatePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "날짜 선택" : "Select date";
+}
+function defaultRangePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "시작일 ~ 종료일" : "Start date – end date";
+}
+
 /* ───────── Icons ───────── */
 
 function CalendarIcon() {
@@ -39,6 +48,8 @@ interface DatePickerContextValue {
   setFocusedDate: (date: Date) => void;
   formatDate: (date: Date) => string;
   placeholder: string;
+  locale: string;
+  messages?: CalendarMessages;
   min?: Date;
   max?: Date;
   disabled?: boolean;
@@ -76,10 +87,13 @@ export interface DatePickerProps {
   /** 선택 가능 최대 날짜 (포함). 이후 날짜는 비활성. */
   max?: Date;
   /**
-   * 미선택 상태의 트리거 텍스트.
-   * @default "날짜 선택"
+   * 미선택 상태의 트리거 텍스트. 미지정 시 `locale` 기반 기본값.
    */
   placeholder?: string;
+  /** BCP47 로케일. 내부 Calendar 와 placeholder 에 모두 적용. @default "ko-KR" */
+  locale?: string;
+  /** 내부 Calendar 의 nav/select aria-label override. */
+  messages?: CalendarMessages;
   /** 비활성. 트리거 클릭·키보드 모두 차단. */
   disabled?: boolean;
   /** 읽기 전용. 트리거 표시는 유지하되 popover가 열리지 않는다. */
@@ -119,7 +133,9 @@ export function DatePicker({
   formatDate = formatDefault,
   min,
   max,
-  placeholder = "날짜 선택",
+  placeholder,
+  locale = DEFAULT_LOCALE,
+  messages,
   disabled,
   readOnly,
   "aria-invalid": ariaInvalid,
@@ -128,6 +144,7 @@ export function DatePicker({
   container,
   children,
 }: DatePickerProps) {
+  const resolvedPlaceholder = placeholder ?? defaultDatePlaceholder(locale);
   const isControlled = value !== undefined;
   const [internal, setInternal] = React.useState<Date | undefined>(defaultValue);
   const selected = isControlled ? value : internal;
@@ -160,7 +177,9 @@ export function DatePicker({
       focusedDate,
       setFocusedDate,
       formatDate,
-      placeholder,
+      placeholder: resolvedPlaceholder,
+      locale,
+      messages,
       min,
       max,
       disabled,
@@ -174,7 +193,9 @@ export function DatePicker({
       open,
       focusedDate,
       formatDate,
-      placeholder,
+      resolvedPlaceholder,
+      locale,
+      messages,
       min,
       max,
       disabled,
@@ -355,6 +376,8 @@ export function DatePickerCalendar() {
       onMonthChange={ctx.setFocusedDate}
       min={ctx.min}
       max={ctx.max}
+      locale={ctx.locale}
+      messages={ctx.messages}
     />
   );
 }
@@ -407,10 +430,13 @@ export interface DateRangePickerProps {
   /** 선택 가능 최대 날짜. */
   max?: Date;
   /**
-   * 미선택 상태의 트리거 텍스트.
-   * @default "시작일 ~ 종료일"
+   * 미선택 상태의 트리거 텍스트. 미지정 시 `locale` 기반 기본값.
    */
   placeholder?: string;
+  /** BCP47 로케일. @default "ko-KR" */
+  locale?: string;
+  /** 내부 Calendar 의 nav/select aria-label override. */
+  messages?: CalendarMessages;
   /** 비활성. */
   disabled?: boolean;
   /** 읽기 전용. popover가 열리지 않는다. */
@@ -438,7 +464,9 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
       formatDate = formatDefault,
       min,
       max,
-      placeholder = "시작일 ~ 종료일",
+      placeholder,
+      locale = DEFAULT_LOCALE,
+      messages,
       disabled,
       readOnly,
       "aria-invalid": ariaInvalid,
@@ -447,6 +475,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
     },
     ref,
   ) {
+    const resolvedPlaceholder = placeholder ?? defaultRangePlaceholder(locale);
     const isControlled = value !== undefined;
     const [internal, setInternal] = React.useState<DateRange | undefined>(defaultValue);
     const selected = isControlled ? value : internal;
@@ -485,7 +514,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
           }}
         >
           <span className={cn(styles["date-picker__value"], !displayText && styles["date-picker__placeholder"])}>
-            {displayText ?? placeholder}
+            {displayText ?? resolvedPlaceholder}
           </span>
           <span className={styles["date-picker__icon"]} aria-hidden>
             <CalendarIcon />
@@ -509,6 +538,8 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
                   onMonthChange={setCalendarMonth}
                   min={min}
                   max={max}
+                  locale={locale}
+                  messages={messages}
                 />
               </BasePopover.Popup>
             </BasePopover.Positioner>

package/data/registry/react/components/date-picker/index.tailwind.tsx

@@ -2,7 +2,7 @@
 
 import * as React from "react";
 import { Popover as BasePopover } from "@base-ui/react/popover";
-import { Calendar, type DateRange } from "../calendar";
+import { Calendar, DEFAULT_LOCALE, type CalendarMessages, type DateRange } from "../calendar";
 
 import { cn } from "@SH_UI_UTILS@";
 export type { DateRange };
@@ -12,6 +12,15 @@ const formatDefault = (d: Date) =>
   `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 const startOfMonth = (d: Date) => new Date(d.getFullYear(), d.getMonth(), 1);
 
+function defaultDatePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "날짜 선택" : "Select date";
+}
+function defaultRangePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "시작일 ~ 종료일" : "Start date – end date";
+}
+
 const triggerClasses =
   "inline-flex items-center justify-between w-full h-[var(--control-md)] px-[var(--space-3)] bg-background text-foreground border border-border rounded-[var(--radius)] font-[inherit] text-[length:var(--text-sm)] leading-none cursor-pointer transition-[border-color,box-shadow] duration-[var(--duration-fast)] hover:not-disabled:border-border-strong focus-visible:outline-none focus-visible:border-foreground focus-visible:shadow-[0_0_0_1px_var(--foreground)] disabled:opacity-[var(--opacity-disabled)] disabled:cursor-not-allowed disabled:bg-background-subtle aria-[invalid=true]:border-danger aria-[invalid=true]:focus-visible:shadow-[0_0_0_1px_var(--danger)] [@media(hover:none)_and_(pointer:coarse)]:h-11 [@media(hover:none)_and_(pointer:coarse)]:text-[length:var(--text-base)]";
 
@@ -36,6 +45,8 @@ interface DatePickerContextValue {
   setFocusedDate: (date: Date) => void;
   formatDate: (date: Date) => string;
   placeholder: string;
+  locale: string;
+  messages?: CalendarMessages;
   min?: Date; max?: Date; disabled?: boolean; readOnly?: boolean;
   ariaInvalid?: boolean | "true";
   closeOnSelect: boolean;
@@ -54,7 +65,8 @@ export interface DatePickerProps {
   onValueChange?: (date: Date | undefined) => void;
   formatDate?: (date: Date) => string;
   min?: Date; max?: Date;
-  placeholder?: string; disabled?: boolean; readOnly?: boolean;
+  placeholder?: string; locale?: string; messages?: CalendarMessages;
+  disabled?: boolean; readOnly?: boolean;
   "aria-invalid"?: boolean | "true";
   className?: string; closeOnSelect?: boolean;
   container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
@@ -63,9 +75,10 @@ export interface DatePickerProps {
 
 export function DatePicker({
   value, defaultValue, onValueChange, formatDate = formatDefault,
-  min, max, placeholder = "날짜 선택", disabled, readOnly,
+  min, max, placeholder, locale = DEFAULT_LOCALE, messages, disabled, readOnly,
   "aria-invalid": ariaInvalid, className, closeOnSelect = true, container, children,
 }: DatePickerProps) {
+  const resolvedPlaceholder = placeholder ?? defaultDatePlaceholder(locale);
   const isControlled = value !== undefined;
   const [internal, setInternal] = React.useState<Date | undefined>(defaultValue);
   const selected = isControlled ? value : internal;
@@ -84,9 +97,10 @@ export function DatePicker({
   const ctx = React.useMemo<DatePickerContextValue>(
     () => ({
       selected, setSelected, open, setOpen, focusedDate, setFocusedDate,
-      formatDate, placeholder, min, max, disabled, readOnly, ariaInvalid, closeOnSelect,
+      formatDate, placeholder: resolvedPlaceholder, locale, messages,
+      min, max, disabled, readOnly, ariaInvalid, closeOnSelect,
     }),
-    [selected, setSelected, open, focusedDate, formatDate, placeholder, min, max, disabled, readOnly, ariaInvalid, closeOnSelect],
+    [selected, setSelected, open, focusedDate, formatDate, resolvedPlaceholder, locale, messages, min, max, disabled, readOnly, ariaInvalid, closeOnSelect],
   );
 
   return (
@@ -187,6 +201,8 @@ export function DatePickerCalendar() {
       onMonthChange={ctx.setFocusedDate}
       min={ctx.min}
       max={ctx.max}
+      locale={ctx.locale}
+      messages={ctx.messages}
     />
   );
 }
@@ -221,7 +237,8 @@ export interface DateRangePickerProps {
   onValueChange?: (range: DateRange | undefined) => void;
   formatDate?: (date: Date) => string;
   min?: Date; max?: Date;
-  placeholder?: string; disabled?: boolean; readOnly?: boolean;
+  placeholder?: string; locale?: string; messages?: CalendarMessages;
+  disabled?: boolean; readOnly?: boolean;
   "aria-invalid"?: boolean | "true";
   className?: string;
   container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
@@ -230,9 +247,10 @@ export interface DateRangePickerProps {
 export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePickerProps>(
   function DateRangePicker(
     { value, defaultValue, onValueChange, formatDate = formatDefault, min, max,
-      placeholder = "시작일 ~ 종료일", disabled, readOnly, "aria-invalid": ariaInvalid, className, container },
+      placeholder, locale = DEFAULT_LOCALE, messages, disabled, readOnly, "aria-invalid": ariaInvalid, className, container },
     ref,
   ) {
+    const resolvedPlaceholder = placeholder ?? defaultRangePlaceholder(locale);
     const isControlled = value !== undefined;
     const [internal, setInternal] = React.useState<DateRange | undefined>(defaultValue);
     const selected = isControlled ? value : internal;
@@ -262,7 +280,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
           onClick={(e) => { if (readOnly) e.preventDefault(); }}
         >
           <span className={cn("overflow-hidden text-ellipsis whitespace-nowrap", !displayText && "text-foreground-subtle")}>
-            {displayText ?? placeholder}
+            {displayText ?? resolvedPlaceholder}
           </span>
           <span className="shrink-0 inline-flex text-foreground-muted ml-[var(--space-2)]" aria-hidden>
             <CalendarIcon />
@@ -281,6 +299,8 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
                   onMonthChange={setCalendarMonth}
                   min={min}
                   max={max}
+                  locale={locale}
+                  messages={messages}
                 />
               </BasePopover.Popup>
             </BasePopover.Positioner>