# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/ru/docs/platform/core/reference/utility-functions/formatting/format-relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Форматирование значений относительного времени без экземпляра GT. Справка по API для formatRelativeTime.

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) — это отдельная служебная функция из основной библиотеки General Translation, которая форматирует значение относительного времени с явно указанной единицей времени в соответствии с правилами конкретной локали. Она возвращает строки вроде "2 часа назад" или "через 3 дня".

## Обзор [#overview]

Импортируйте `formatRelativeTime` напрямую из `generaltranslation` и вызовите её, передав значение, единицу времени и объект параметров. Для этого не нужен API-ключ или экземпляр [GT](/docs/platform/core/reference/gt-class/constructor). Если вам нужно форматирование через экземпляр с наследованием его локали, используйте метод [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor). Чтобы единица времени выбиралась автоматически на основе `Date`, используйте [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date).

```typescript
import { formatRelativeTime } from 'generaltranslation';

const formatted = formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto',
});
// Возвращает: "yesterday"
```

Сигнатура:

```typescript
formatRelativeTime(
  value: number,
  unit: Intl.RelativeTimeFormatUnit,
  options?: { locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>
): string
```

## Как это работает [#how-it-works]

* **Используемый API.** В основе используется [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* **Соглашение о знаках.** Отрицательные значения относятся к прошлому, положительные — к будущему.
* **Числовой режим.** По умолчанию используется `numeric: 'auto'`, поэтому значения вроде `-1 day` дают «вчера» вместо «1 день назад». Установите `numeric: 'always'`, чтобы всегда получать числовой формат.
* **Выбор локали.** Если `locales` не указан, используется локаль библиотеки по умолчанию — `en`.
* **Кэширование.** Результаты кэшируются для повышения производительности при повторном использовании одних и тех же комбинаций локалей и параметров.

## Параметры [#parameters]

| Параметр              | Описание                                                                                      | Тип                                                                                  | Необязательный | По умолчанию |
| --------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------- | ------------ |
| [`value`](#value)     | Значение относительного времени (отрицательное — для прошлого, положительное — для будущего). | `number`                                                                             | Нет            | —            |
| [`unit`](#unit)       | Единица времени.                                                                              | `Intl.RelativeTimeFormatUnit`                                                        | Нет            | —            |
| [`options`](#options) | Параметры форматирования, включая целевую локаль или локали.                                  | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | Да             | `{}`         |

### `value` [#value]

**Type** `number` · **Обязательный**

Значение относительного времени. Отрицательные числа обозначают прошлое, положительные — будущее.

### `unit` [#unit]

**Тип** `Intl.RelativeTimeFormatUnit` · **Обязательно**

Единица времени. Допускаются формы единственного и множественного числа: `'second'`/`'seconds'`, `'minute'`/`'minutes'`, `'hour'`/`'hours'`, `'day'`/`'days'`, `'week'`/`'weeks'`, `'month'`/`'months'`, `'quarter'`/`'quarters'` и `'year'`/`'years'`.

### `options` [#options]

**Тип** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **Необязательный** · **По умолчанию** `{}`

Параметры форматирования. В таблице перечислены распространённые параметры, представленные опубликованными типами Ядро, и их фактические значения по умолчанию в Ядро. (Дополнительные сведения о стандарте и среде выполнения см. в [параметрах конструктора `Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)).

| Свойство        | Описание                                     | Тип                             | Необязательное | По умолчанию |
| --------------- | -------------------------------------------- | ------------------------------- | -------------- | ------------ |
| `locales`       | Локаль(и) для форматирования.                | `string \| string[]`            | Да             | `en`         |
| `numeric`       | Всегда ли использовать числовой формат.      | `'always' \| 'auto'`            | Да             | `'auto'`     |
| `style`         | Длина результата.                            | `'long' \| 'short' \| 'narrow'` | Да             | `'long'`     |
| `localeMatcher` | Используемый алгоритм сопоставления локалей. | `'best fit' \| 'lookup'`        | Да             | `'best fit'` |

Ядро изменяет исходное значение по умолчанию `numeric` с `'always'` на `'auto'`; остальные стандартные значения по умолчанию берутся из `Intl.RelativeTimeFormat`.

## Возвращает [#returns]

**Тип** `string`

Строка относительного времени в отформатированном виде.

## Примеры [#examples]

```typescript
import { formatRelativeTime } from 'generaltranslation';

// Прошедшее время
console.log(formatRelativeTime(-2, 'hour', { locales: 'en-US' }));
// Вывод: "2 hours ago"

// Будущее время
console.log(formatRelativeTime(3, 'day', { locales: 'en-US' }));
// Вывод: "in 3 days"

// С numeric: 'auto' (по умолчанию)
console.log(formatRelativeTime(-1, 'day', { locales: 'en-US' }));
// Вывод: "yesterday"
```

```typescript
// Стили форматирования

// Длинный стиль (по умолчанию)
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'long',
}));
// Вывод: "2 days ago"

// Короткий стиль
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'short',
}));
// Вывод: "2 days ago" (может быть сокращено в некоторых локалях)

// Узкий стиль
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'narrow',
}));
// Вывод: "2d ago"
```

```typescript
// Несколько локалей
const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

locales.forEach((locale) => {
  console.log(`${locale}: ${formatRelativeTime(-3, 'hour', { locales: locale })}`);
});
// Вывод:
// en-US: 3 hours ago
// fr-FR: il y a 3 heures
// ja-JP: 3 時間前
// de-DE: vor 3 Stunden
```

## Примечания [#notes]

* По умолчанию используются `numeric: 'auto'` и `style: 'long'`.
* При `numeric: 'auto'` значения вроде `-1 day` дают «вчера» вместо «1 day ago».
* В основе используется [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* Результаты кэшируются для повышения производительности при повторном использовании одних и тех же комбинаций локали и параметров.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.