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

문제

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

사용자는 날짜가 자신이 배우고 일상적으로 사용하는 형식으로 표시되기를 기대합니다. 한 사용자에게 자연스러워 보이는 날짜가 다른 사용자에게는 모호하거나 어색할 수 있습니다. 로케일 인식 형식 지정이 없으면 날짜는 사용자 경험을 저해하고 애플리케이션을 덜 전문적으로 보이게 만드는 마찰 요인이 됩니다.

솔루션

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

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

단계

1. useIntl 훅으로 날짜를 포맷하는 컴포넌트 생성

useIntl 훅을 사용하여 날짜 값을 로케일 인식 문자열로 변환하는 formatDate 메서드에 액세스하세요.

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 메서드는 날짜 표시에 대한 로케일의 규칙을 적용합니다. options 객체는 날짜의 어떤 부분이 표시될지와 세부 수준을 제어합니다. 포맷된 문자열은 컴포넌트 트리 상위의 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 fragment로 렌더링합니다. IntlProvider 컨텍스트의 로케일을 사용하며 명령형 API와 동일한 포맷 규칙을 적용합니다. 이 접근 방식은 컴포넌트 트리의 해당 부분에서 포맷된 날짜만 필요한 경우에 적합합니다.

4. 시간 정보와 함께 날짜 포맷

시간 및 분 옵션을 추가하여 단일 포맷된 문자열에 날짜와 시간을 모두 표시합니다.

import { useIntl } from "react-intl";

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

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

hour 및 minute 옵션을 추가하면 날짜와 시간이 결합된 문자열이 생성됩니다. 로케일은 12시간 또는 24시간 형식을 사용할지, 날짜와 시간 부분을 어떻게 구분할지 결정합니다. 이를 통해 타임스탬프 표시에 대한 지역적 기대에 부합하는 일관된 포맷을 유지합니다.