sh-ui-cli 0.52.3 → 0.53.0

package/data/changelog/versions.json

@@ -2,6 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.53.0",
+      "date": "2026-05-04",
+      "title": "Calendar/DatePicker i18n — locale + messages prop",
+      "type": "minor",
+      "highlights": [
+        "**Calendar `locale` prop 추가** — BCP47 로케일(예: `\"en-US\"`, `\"ja-JP\"`) 한 줄로 요일·월 헤더·연도/월 dropdown 라벨이 모두 `Intl.DateTimeFormat` 으로 자동 생성. 한국어만 지원되던 기존 동작에서 다국어 지원으로 확장. 기본값은 `\"ko-KR\"` 유지 — 기존 사용자 영향 없음.",
+        "**`messages` prop 으로 aria-label override** — Nav 버튼(`이전 해`/`다음 달` 등) 과 select aria-label(`연도`/`월`) 을 `CalendarMessages` 객체로 한 번에 교체. ko/en 은 내장 기본값 제공, 그 외 언어는 직접 문자열 전달.",
+        "**DatePicker / DateRangePicker 도 `locale` 전파** — 내부 Calendar 에 자동 전달되고 placeholder(`날짜 선택`/`Select date` / `시작일 ~ 종료일`/`Start date – end date`) 도 locale 기반 자동 결정. `placeholder` 를 직접 넘기면 그게 우선.",
+        "**개별 포맷터 prop 은 그대로 유효** — `weekdayLabels`/`formatMonthLabel`/`CalendarYearSelect.formatYear` 등 기존 세밀 override 는 locale 보다 우선. 마이그레이션 불필요.",
+        "**새 export** — `Calendar` 모듈에서 `DEFAULT_LOCALE` 상수와 `CalendarMessages` 타입을 추가로 노출."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.53.0"
+    },
     {
       "version": "0.52.3",
       "date": "2026-05-04",

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

@@ -12,8 +12,8 @@ import styles from "./styles.module.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(styles.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(styles["calendar__select-trigger"], className)}
-        aria-label="연도"
+        aria-label={ctx.messages.yearSelectLabel}
       >
-        <span className={styles["calendar__select-value"]}>{formatYear(year)}</span>
+        <span className={styles["calendar__select-value"]}>{resolvedFormat(year)}</span>
       </SelectTrigger>
       <SelectContent className={styles["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(styles["calendar__select-trigger"], className)}
-        aria-label="월"
+        aria-label={ctx.messages.monthSelectLabel}
       >
-        <span className={styles["calendar__select-value"]}>{formatMonth(month)}</span>
+        <span className={styles["calendar__select-value"]}>{resolvedFormat(month)}</span>
       </SelectTrigger>
       <SelectContent className={styles["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/calendar/index.tailwind.tsx

@@ -5,7 +5,9 @@ import { Select, SelectContent, SelectItem, SelectTrigger } from "../select";
 
 
 import { cn } from "@SH_UI_UTILS@";
-const DEFAULT_WEEKDAYS_KO = ["일", "월", "화", "수", "목", "금", "토"] as const;
+
+/** 미지정 시의 기본 로케일. 기존 동작(한국어) 보존. */
+export const DEFAULT_LOCALE = "ko-KR";
 
 const isSameDay = (a: Date, b: Date) =>
   a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
@@ -14,7 +16,53 @@ const startOfMonth = (d: Date) => new Date(d.getFullYear(), d.getMonth(), 1);
 const addMonths = (d: Date, n: number) => new Date(d.getFullYear(), d.getMonth() + n, 1);
 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}월`;
+
+function deriveWeekdayLabels(locale: string): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: "short" });
+  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));
+}
+
+export interface CalendarMessages {
+  prevYear?: string;
+  nextYear?: string;
+  prevMonth?: string;
+  nextMonth?: string;
+  yearSelectLabel?: string;
+  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);
@@ -49,6 +97,10 @@ interface CalendarCommonProps {
   weekStartsOn?: 0 | 1;
   weekdayLabels?: readonly string[];
   formatMonthLabel?: (year: number, month: number) => string;
+  /** BCP47 로케일. @default "ko-KR" */
+  locale?: string;
+  /** Nav/select aria-label override. */
+  messages?: CalendarMessages;
   fromYear?: number; toYear?: number;
   className?: string;
   "aria-label"?: string;
@@ -92,6 +144,9 @@ interface CalendarContextValue {
   weekdayLabels: string[];
   showOutsideDays: boolean;
   formatMonthLabel: (year: number, month: number) => string;
+  defaultFormatYear: (y: number) => string;
+  defaultFormatMonth: (m: number) => string;
+  messages: Required<CalendarMessages>;
   ariaLabel?: string;
   isSelected: (date: Date) => boolean;
   isInRange: (date: Date) => { inRange: boolean; isStart: boolean; isEnd: boolean };
@@ -117,7 +172,9 @@ export function Calendar(props: CalendarProps) {
     numberOfMonths: numberOfMonthsProp = 1,
     min, max, disabled, showOutsideDays = true, weekStartsOn = 0,
     weekdayLabels: weekdayLabelsProp,
-    formatMonthLabel = defaultMonthLabel,
+    formatMonthLabel: formatMonthLabelProp,
+    locale = DEFAULT_LOCALE,
+    messages: messagesProp,
     fromYear, toYear, className, "aria-label": ariaLabel, children,
   } = props as CalendarCommonProps & { mode?: CalendarMode };
 
@@ -163,10 +220,21 @@ export function Calendar(props: CalendarProps) {
     return new Date();
   });
 
+  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],
+  );
+
   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;
 
   const nowYear = new Date().getFullYear();
   const resolvedFromYear = fromYear ?? min?.getFullYear() ?? nowYear - 10;
@@ -275,7 +343,11 @@ export function Calendar(props: CalendarProps) {
     nextMonth: () => setMonth(addMonths(currentMonth, 1)),
     prevYear: () => setMonth(addMonths(currentMonth, -12)),
     nextYear: () => setMonth(addMonths(currentMonth, 12)),
-    weekStartsOn, weekdayLabels, showOutsideDays, formatMonthLabel, ariaLabel,
+    weekStartsOn, weekdayLabels, showOutsideDays, formatMonthLabel,
+    defaultFormatYear: localeYearLabel,
+    defaultFormatMonth: localeMonthSelectLabel,
+    messages: resolvedMessages,
+    ariaLabel,
     isSelected: isDateSelected, isInRange: getRangeState, isDisabled: isDateDisabled,
     handleSelect,
     setHoverDate: mode === "range" ? setHoverDate : () => {},
@@ -332,7 +404,7 @@ export interface CalendarNavButtonProps extends Omit<React.ButtonHTMLAttributes<
 function makeNavButton(
   displayName: string,
   defaultIcon: React.ReactNode,
-  defaultLabel: string,
+  resolveDefaultLabel: (ctx: CalendarContextValue) => string,
   resolveHandler: (ctx: CalendarContextValue) => () => void,
 ) {
   const Component = React.forwardRef<HTMLButtonElement, CalendarNavButtonProps>(
@@ -343,7 +415,7 @@ function makeNavButton(
           ref={ref}
           type="button"
           className={cn(navButtonClasses, className)}
-          aria-label={ariaLabel ?? defaultLabel}
+          aria-label={ariaLabel ?? resolveDefaultLabel(ctx)}
           onClick={(e) => { resolveHandler(ctx)(); onClick?.(e); }}
           {...props}
         >
@@ -356,10 +428,10 @@ function makeNavButton(
   return Component;
 }
 
-export const CalendarPrevYearButton = makeNavButton("CalendarPrevYearButton", <ChevronDoubleLeftIcon />, "이전 해", (ctx) => ctx.prevYear);
-export const CalendarNextYearButton = makeNavButton("CalendarNextYearButton", <ChevronDoubleRightIcon />, "다음 해", (ctx) => ctx.nextYear);
-export const CalendarPrevMonthButton = makeNavButton("CalendarPrevMonthButton", <ChevronLeftIcon />, "이전 달", (ctx) => ctx.prevMonth);
-export const CalendarNextMonthButton = makeNavButton("CalendarNextMonthButton", <ChevronRightIcon />, "다음 달", (ctx) => ctx.nextMonth);
+export const CalendarPrevYearButton = makeNavButton("CalendarPrevYearButton", <ChevronDoubleLeftIcon />, (ctx) => ctx.messages.prevYear, (ctx) => ctx.prevYear);
+export const CalendarNextYearButton = makeNavButton("CalendarNextYearButton", <ChevronDoubleRightIcon />, (ctx) => ctx.messages.nextYear, (ctx) => ctx.nextYear);
+export const CalendarPrevMonthButton = makeNavButton("CalendarPrevMonthButton", <ChevronLeftIcon />, (ctx) => ctx.messages.prevMonth, (ctx) => ctx.prevMonth);
+export const CalendarNextMonthButton = makeNavButton("CalendarNextMonthButton", <ChevronRightIcon />, (ctx) => ctx.messages.nextMonth, (ctx) => ctx.nextMonth);
 
 const calendarSelectTriggerClasses =
   "min-w-0 h-7 gap-[var(--space-1)] px-[var(--space-2)] bg-transparent border-transparent font-semibold text-[length:var(--text-sm)] text-foreground hover:not-disabled:bg-background-muted hover:not-disabled:border-transparent data-[popup-open]:bg-background-muted data-[popup-open]:border-transparent";
@@ -369,17 +441,18 @@ export interface CalendarYearSelectProps {
   formatYear?: (year: number) => string;
 }
 
-export function CalendarYearSelect({ className, formatYear = (y) => `${y}년` }: CalendarYearSelectProps) {
+export function CalendarYearSelect({ className, formatYear }: CalendarYearSelectProps) {
   const ctx = useCalendarContext("CalendarYearSelect");
+  const resolvedFormat = formatYear ?? ctx.defaultFormatYear;
   const year = ctx.visibleMonth.getFullYear();
   const items = ctx.yearOptions.includes(year) ? ctx.yearOptions : [...ctx.yearOptions, year].sort((a, b) => a - b);
   return (
     <Select value={String(year)} onValueChange={(v) => ctx.setYearForVisible(Number(v))}>
-      <SelectTrigger className={cn(calendarSelectTriggerClasses, className)} aria-label="연도">
-        <span>{formatYear(year)}</span>
+      <SelectTrigger className={cn(calendarSelectTriggerClasses, className)} aria-label={ctx.messages.yearSelectLabel}>
+        <span>{resolvedFormat(year)}</span>
       </SelectTrigger>
       <SelectContent>
-        {items.map((y) => <SelectItem key={y} value={String(y)}>{formatYear(y)}</SelectItem>)}
+        {items.map((y) => <SelectItem key={y} value={String(y)}>{resolvedFormat(y)}</SelectItem>)}
       </SelectContent>
     </Select>
   );
@@ -390,16 +463,17 @@ export interface CalendarMonthSelectProps {
   formatMonth?: (month: number) => string;
 }
 
-export function CalendarMonthSelect({ className, formatMonth = (m) => `${m + 1}월` }: CalendarMonthSelectProps) {
+export function CalendarMonthSelect({ className, formatMonth }: CalendarMonthSelectProps) {
   const ctx = useCalendarContext("CalendarMonthSelect");
+  const resolvedFormat = formatMonth ?? ctx.defaultFormatMonth;
   const month = ctx.visibleMonth.getMonth();
   return (
     <Select value={String(month)} onValueChange={(v) => ctx.setMonthForVisible(Number(v))}>
-      <SelectTrigger className={cn(calendarSelectTriggerClasses, className)} aria-label="월">
-        <span>{formatMonth(month)}</span>
+      <SelectTrigger className={cn(calendarSelectTriggerClasses, className)} aria-label={ctx.messages.monthSelectLabel}>
+        <span>{resolvedFormat(month)}</span>
       </SelectTrigger>
       <SelectContent>
-        {Array.from({ length: 12 }, (_, m) => <SelectItem key={m} value={String(m)}>{formatMonth(m)}</SelectItem>)}
+        {Array.from({ length: 12 }, (_, m) => <SelectItem key={m} value={String(m)}>{resolvedFormat(m)}</SelectItem>)}
       </SelectContent>
     </Select>
   );

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>

package/data/registry/react/components/date-picker/index.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.css";
 
 import { cn } from "@SH_UI_UTILS@";
@@ -17,6 +17,18 @@ const formatDefault = (d: Date) =>
 const startOfMonth = (d: Date) =>
   new Date(d.getFullYear(), d.getMonth(), 1);
 
+/** locale 기반 단일 날짜 placeholder. 한국어 외에는 영어 fallback. */
+function defaultDatePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "날짜 선택" : "Select date";
+}
+
+/** locale 기반 범위 placeholder. */
+function defaultRangePlaceholder(locale: string): string {
+  const lang = locale.toLowerCase().split(/[-_]/)[0];
+  return lang === "ko" ? "시작일 ~ 종료일" : "Start date – end date";
+}
+
 /* ───────── Icons ───────── */
 
 function CalendarIcon() {
@@ -39,6 +51,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 +90,16 @@ export interface DatePickerProps {
   /** 선택 가능 최대 날짜 (포함). 이후 날짜는 비활성. */
   max?: Date;
   /**
-   * 미선택 상태의 트리거 텍스트.
-   * @default "날짜 선택"
+   * 미선택 상태의 트리거 텍스트. 미지정 시 `locale` 기반 자동 생성("날짜 선택" / "Select date").
    */
   placeholder?: string;
+  /**
+   * BCP47 로케일. 내부 Calendar 와 placeholder 기본값에 모두 적용된다.
+   * @default "ko-KR"
+   */
+  locale?: string;
+  /** 내부 Calendar 의 nav/select aria-label override. */
+  messages?: CalendarMessages;
   /** 비활성. 트리거 클릭·키보드 모두 차단. */
   disabled?: boolean;
   /** 읽기 전용. 트리거 표시는 유지하되 popover가 열리지 않는다. */
@@ -119,7 +139,9 @@ export function DatePicker({
   formatDate = formatDefault,
   min,
   max,
-  placeholder = "날짜 선택",
+  placeholder,
+  locale = DEFAULT_LOCALE,
+  messages,
   disabled,
   readOnly,
   "aria-invalid": ariaInvalid,
@@ -128,6 +150,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 +183,9 @@ export function DatePicker({
       focusedDate,
       setFocusedDate,
       formatDate,
-      placeholder,
+      placeholder: resolvedPlaceholder,
+      locale,
+      messages,
       min,
       max,
       disabled,
@@ -174,7 +199,9 @@ export function DatePicker({
       open,
       focusedDate,
       formatDate,
-      placeholder,
+      resolvedPlaceholder,
+      locale,
+      messages,
       min,
       max,
       disabled,
@@ -355,6 +382,8 @@ export function DatePickerCalendar() {
       onMonthChange={ctx.setFocusedDate}
       min={ctx.min}
       max={ctx.max}
+      locale={ctx.locale}
+      messages={ctx.messages}
     />
   );
 }
@@ -407,10 +436,16 @@ export interface DateRangePickerProps {
   /** 선택 가능 최대 날짜. */
   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가 열리지 않는다. */
@@ -438,7 +473,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 +484,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 +523,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
           }}
         >
           <span className={cn("sh-ui-date-picker__value", !displayText && "sh-ui-date-picker__placeholder")}>
-            {displayText ?? placeholder}
+            {displayText ?? resolvedPlaceholder}
           </span>
           <span className="sh-ui-date-picker__icon" aria-hidden>
             <CalendarIcon />
@@ -509,6 +547,8 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
                   onMonthChange={setCalendarMonth}
                   min={min}
                   max={max}
+                  locale={locale}
+                  messages={messages}
                 />
               </BasePopover.Popup>
             </BasePopover.Positioner>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.52.3",
+  "version": "0.53.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {