Локальные настройки для экземпляров

timeago.js придерживается функционального стиля — вместо создания экземпляров с состоянием используются функции с параметрами. Локальные настройки передаются непосредственно при каждом вызове. Это делает поведение явным и предсказуемым без скрытого состояния.

Локаль как параметр функции

Наиболее часто используемая локальная настройка — локаль, передаётся вторым аргументом:

import { format } from 'timeago.js';

format(date, 'ru');     // Русский
format(date, 'de');     // Немецкий
format(date, 'zh_CN'); // Китайский

Каждый вызов может использовать свою локаль независимо от других.

Опорная дата (relativeDate)

Третий аргумент функции format — объект опций, позволяющий задать дату, относительно которой вычисляется разница:

import { format } from 'timeago.js';

const base   = new Date('2025-06-01T00:00:00Z');
const target = new Date('2025-05-26T00:00:00Z');

format(target, 'ru', { relativeDate: base });
// → "5 дней назад"

По умолчанию опорная дата — new Date() (текущий момент).

Использование relativeDate для тестирования

relativeDate особенно полезна в тестах, где нужно детерминированное поведение:

import { format } from 'timeago.js';

const fixedNow = new Date('2025-05-26T12:00:00Z');
const created  = new Date('2025-05-26T10:00:00Z');

const result = format(created, 'ru', { relativeDate: fixedNow });
// → "2 часа назад"

Нет необходимости мокировать Date.now() — достаточно передать опорную дату явно.

Локальные настройки в render()

Функция render принимает локаль вторым аргументом:

import { render } from 'timeago.js';

const nodes = document.querySelectorAll('.time');

render(nodes, 'ru');

Если нужно применить разные локали к разным наборам элементов:

const russianNodes = document.querySelectorAll('.time-ru');
const englishNodes = document.querySelectorAll('.time-en');

render(russianNodes, 'ru');
render(englishNodes, 'en_US');

Настройка через data-атрибуты

Для гибкого управления локалью на уровне элемента можно считывать значение из data-атрибута:

<time class="ago" datetime="2025-05-26T10:00:00Z" data-locale="ru"></time>
<time class="ago" datetime="2025-05-26T10:00:00Z" data-locale="de"></time>
import { format } from 'timeago.js';

document.querySelectorAll('.ago').forEach(el => {
  const locale = el.dataset.locale || 'en_US';
  const date   = el.getAttribute('datetime');
  el.textContent = format(date, locale);
});

Создание локального форматтера

Функциональный подход позволяет создавать специализированные форматтеры:

import { format } from 'timeago.js';

const formatRu = (date) => format(date, 'ru');
const formatDe = (date) => format(date, 'de');
const formatRelative = (date, base) => format(date, 'ru', { relativeDate: base });

Компонент с локальной настройкой (React)

import { format } from 'timeago.js';

interface Props {
  date: Date;
  locale?: string;
  relativeTo?: Date;
}

function TimeAgo({ date, locale = 'ru', relativeTo }: Props) {
  const options = relativeTo ? { relativeDate: relativeTo } : undefined;
  return <time dateTime={date.toISOString()}>{format(date, locale, options)}</time>;
}

Каждый экземпляр компонента работает со своими настройками — никакого глобального состояния.

Хук с локальными настройками (React)

import { useState, useEffect } from 'react';
import { format } from 'timeago.js';

function useTimeAgo(date: Date, locale: string = 'ru'): string {
  const [label, setLabel] = useState(() => format(date, locale));

  useEffect(() => {
    const interval = setInterval(() => {
      setLabel(format(date, locale));
    }, 30000);

    return () => clearInterval(interval);
  }, [date, locale]);

  return label;
}

Разные настройки для разных контекстов

В одном приложении могут использоваться разные форматы в зависимости от контекста:

import { format } from 'timeago.js';

// В ленте новостей — краткий формат
const feedLabel = format(post.createdAt, 'ru');

// В деталях публикации — другая локаль
const detailLabel = format(post.createdAt, 'ru_verbose');

// В системных логах — относительно фиксированного момента
const logLabel = format(event.time, 'en_US', { relativeDate: reportBase });

Локальные настройки и SSR

При серверном рендеринге relativeDate позволяет получить детерминированный результат, не зависящий от момента генерации:

// Сервер рендерит страницу в 2025-05-26T12:00:00Z
// Чтобы клиент и сервер показали одинаковый результат:

const renderTime = new Date('2025-05-26T12:00:00Z');

const label = format(post.createdAt, 'ru', { relativeDate: renderTime });

Это позволяет избежать гидрационных несоответствий в React SSR.

Итог: локальные настройки в timeago.js

Настройка Как задаётся
Локаль Второй аргумент format(date, locale)
Опорная дата format(date, locale, { relativeDate: base })
Локаль в render render(nodes, locale)
Автообновление Встроено в render, не настраивается
Оглавление