Как форматировать даты для разных локалей в TanStack Start v1

Проблема

Формат отображения дат не является универсальным. Последовательность 10/12/2025 означает 12 октября в Соединенных Штатах, но 10 декабря в Великобритании. Написание "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 применяет правила отображения даты, характерные для локали. Объект с опциями управляет тем, какие части даты отображаются и с какой степенью детализации. Отформатированная строка адаптируется к локали, заданной в компоненте 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>Опубликовано: {shortDate}</p>
      <p>Полная дата: {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>Заказ оформлен</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-часовой формат времени, а также как разделять части даты и времени. Это обеспечивает соответствие форматирования региональным ожиданиям отображения временных меток.