# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/utility-functions/formatting/format-relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format relative time values without a GT instance. API reference for formatRelativeTime.

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) is a standalone utility function from General Translation's Core library that formats a relative time value with an explicit unit, according to locale-specific conventions. It returns strings such as "2 hours ago" or "in 3 days".

## Overview [#overview]

Import `formatRelativeTime` directly from `generaltranslation` and call it with a value, a unit, and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based formatting that inherits the instance locale, use the [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead. To auto-select the unit from a `Date`, use [`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',
});
// Returns: "yesterday"
```

Signature:

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

## How it works [#how-it-works]

- **Underlying API.** Uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood.
- **Sign convention.** Negative values are in the past; positive values are in the future.
- **Numeric mode.** Defaults to `numeric: 'auto'`, so values like `-1 day` produce "yesterday" instead of "1 day ago". Set `numeric: 'always'` to force numeric output.
- **Locale resolution.** When `locales` is omitted, it falls back to the library default locale, `en`.
- **Caching.** Results are cached internally for performance across repeated locale and options combinations.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`value`](#value) | The relative time value (negative for past, positive for future). | `number` | No | — |
| [`unit`](#unit) | The unit of time. | `Intl.RelativeTimeFormatUnit` | No | — |
| [`options`](#options) | Formatting configuration, including the target locale(s). | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | Yes | `{}` |

### `value` [#value]

**Type** `number` · **Required**

The relative time value. Negative numbers represent the past, positive numbers the future.

### `unit` [#unit]

**Type** `Intl.RelativeTimeFormatUnit` · **Required**

The unit of time. Singular and plural forms are accepted: `'second'`/`'seconds'`, `'minute'`/`'minutes'`, `'hour'`/`'hours'`, `'day'`/`'days'`, `'week'`/`'weeks'`, `'month'`/`'months'`, `'quarter'`/`'quarters'`, and `'year'`/`'years'`.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **Optional** · **Default** `{}`

Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. (See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplemental standard and runtime-specific details).

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Locale(s) for formatting. | `string \| string[]` | Yes | `en` |
| `numeric` | Whether to always use numeric output. | `'always' \| 'auto'` | Yes | `'auto'` |
| `style` | The length of the output. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` |
| `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'` | Yes | `'best fit'` |

Core changes the upstream `numeric` default from `'always'` to `'auto'`; the other standard defaults come from `Intl.RelativeTimeFormat`.

## Returns [#returns]

**Type** `string`

The formatted relative time string.

## Examples [#examples]

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

// Past time
console.log(formatRelativeTime(-2, 'hour', { locales: 'en-US' }));
// Output: "2 hours ago"

// Future time
console.log(formatRelativeTime(3, 'day', { locales: 'en-US' }));
// Output: "in 3 days"

// With numeric: 'auto' (default)
console.log(formatRelativeTime(-1, 'day', { locales: 'en-US' }));
// Output: "yesterday"
```

```typescript
// Formatting styles

// Long style (default)
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'long',
}));
// Output: "2 days ago"

// Short style
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'short',
}));
// Output: "2 days ago" (may be abbreviated in some locales)

// Narrow style
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'narrow',
}));
// Output: "2d ago"
```

```typescript
// Multiple locales
const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

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

## Notes [#notes]

- Defaults to `numeric: 'auto'` and `style: 'long'`.
- With `numeric: 'auto'`, values like `-1 day` produce "yesterday" instead of "1 day ago".
- Uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood.
- Results are cached internally for performance with repeated locale/options combinations.

## Sitemap

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