TanStack Start v1에서 다양한 로케일에 맞게 날짜 형식을 지정하는 방법

지역별 형식으로 날짜 표시하기

문제

날짜는 보편적인 표시 형식이 없습니다. 10/12/2025라는 순서는 미국에서는 10월 12일을 의미하지만 영국에서는 12월 10일을 의미합니다. "Oct 12, 2025"라고 작성하는 것은 영어 월 이름과 특정 순서 규칙을 가정합니다. 모든 지역에는 일, 월, 연도의 순서, 구분 기호 선택, 월 이름의 전체 표기 또는 약어 사용 여부 등 날짜 형식에 대한 고유한 기대치가 있습니다. 애플리케이션이 단일 고정 형식으로 날짜를 표시할 때, 대부분의 지역 사용자에게는 이질적이고 혼란스럽게 느껴집니다.

사용자는 자신이 배우고 일상적으로 사용하는 형식으로 날짜가 표시되기를 기대합니다. 한 사용자 그룹에게 자연스러운 날짜 형식이 다른 그룹에게는 모호하거나 부자연스러울 수 있습니다. 로케일을 고려한 형식 지정이 없으면 날짜는 사용자 경험을 저해하고 애플리케이션이 덜 전문적으로 느껴지게 하는 마찰의 원인이 됩니다.

해결책

사용자의 로케일에 기반하여 날짜 값을 순서, 구분 기호 및 월 이름에 대한 지역 규칙을 따르는 문자열로 변환하여 날짜를 형식화합니다. React-intl은 브라우저의 내장 국제화 API를 사용하여 각 로케일에 맞는 올바른 규칙을 자동으로 적용하는 형식 지정 함수와 컴포넌트를 제공합니다. 이러한 도구에 날짜 값과 선택적 형식 지정 옵션을 전달함으로써, 애플리케이션은 사용자의 언어와 지역에 맞게 명확하고 자연스러운 출력을 생성합니다.

이 접근 방식은 각 로케일에 대한 형식 지정 로직을 수동으로 구현하지 않고도 날짜가 올바르게 표시되도록 보장합니다. 형식 지정은 사용자의 로케일에 맞게 조정되어 날짜를 즉시 인식할 수 있게 하고 인지적 부담을 줄입니다.

단계

1. useIntl 훅을 사용하여 날짜를 형식화하는 컴포넌트 생성

날짜 값을 로케일에 맞는 문자열로 변환하는 formatDate 메서드에 접근하기 위해 useIntl 훅을 사용하세요.

import { useIntl } from "react-intl";

export function EventDate({ date }: { date: Date }) {
  const intl = useIntl();

  return (
    <time dateTime={date.toISOString()}>
      {intl.formatDate(date, {
        year: "numeric",
        month: "long",
        day: "numeric",
      })}
    </time>
  );
}

formatDate 메서드는 날짜 표시에 로케일의 규칙을 적용합니다. 옵션 객체는 날짜의 어떤 부분이 표시되고 그 상세 수준을 제어합니다. 포맷된 문자열은 컴포넌트 트리 상위에 있는 IntlProvider가 제공하는 로케일에 맞게 조정됩니다.

2. 미리 정의된 옵션을 사용하여 특정 스타일로 날짜 포맷하기

짧은 숫자 형식 날짜나 긴 설명형 날짜와 같은 날짜 형식 스타일을 제어하기 위해 다양한 옵션 조합을 전달하세요.

import { useIntl } from "react-intl";

export function ArticleMetadata({ publishedAt }: { publishedAt: Date }) {
  const intl = useIntl();

  const shortDate = intl.formatDate(publishedAt, {
    year: "numeric",
    month: "short",
    day: "numeric",
  });

  const longDate = intl.formatDate(publishedAt, {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "long",
  });

  return (
    <div>
      <p>Published: {shortDate}</p>
      <p>Full date: {longDate}</p>
    </div>
  );
}

month 옵션은 numeric, 2-digit, short, long, narrow와 같은 값을 허용합니다. weekday 옵션은 요일을 추가합니다. 각 로케일은 자체 규칙에 따라 이러한 옵션을 해석하여 출력이 사용자의 기대에 맞게 표시되도록 합니다.

3. 선언적 포맷팅을 위한 FormattedDate 컴포넌트 사용하기

선언적으로 날짜를 렌더링하기 위해 FormattedDate 컴포넌트를 사용하세요. 이 컴포넌트는 formatDate 메서드와 동일한 포맷팅 옵션을 허용합니다.

import { FormattedDate } from "react-intl";

export function OrderSummary({ orderDate }: { orderDate: Date }) {
  return (
    <div>
      <h2>Order placed on</h2>
      <FormattedDate
        value={orderDate}
        year="numeric"
        month="long"
        day="numeric"
      />
    </div>
  );
}

FormattedDate 컴포넌트는 기본적으로 포맷된 날짜를 React 프래그먼트로 렌더링합니다. 이 컴포넌트는 IntlProvider 컨텍스트에서 로케일을 사용하고 명령형 API와 동일한 포맷팅 규칙을 적용합니다. 이 접근 방식은 컴포넌트 트리의 해당 부분에서 포맷된 날짜만 필요할 때 효과적입니다.

4. 시간 정보가 포함된 날짜 형식 지정

시간 및 분 옵션을 추가하여 날짜와 시간을 단일 형식 문자열로 표시할 수 있습니다.

import { useIntl } from "react-intl";

export function AppointmentCard({ scheduledAt }: { scheduledAt: Date }) {
  const intl = useIntl();

  return (
    <div>
      <p>
        예약 시간:{" "}
        {intl.formatDate(scheduledAt, {
          year: "numeric",
          month: "short",
          day: "numeric",
          hour: "numeric",
          minute: "2-digit",
        })}
      </p>
    </div>
  );
}

hour와 minute 옵션을 추가하면 날짜와 시간이 결합된 문자열이 생성됩니다. 로케일에 따라 12시간제 또는 24시간제 시간 형식을 사용할지, 그리고 날짜와 시간 부분을 어떻게 구분할지가 결정됩니다. 이를 통해 타임스탬프 표시에 있어 지역별 기대치와 일관된 형식을 유지할 수 있습니다.