# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx
---

title: formatRelativeTime
description: Format relative time values such as minutes ago or days from now. API reference for formatRelativeTime.

---

Formats a relative time value with an explicit unit according to locale-specific conventions, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.RelativeTimeFormat` API to produce phrases such as "2 hours ago" or "in 3 days".

## Overview [#overview]

Call `formatRelativeTime` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with a numeric value, a time unit, and an optional options object. A negative value is in the past, a positive value is in the future. It returns the formatted string.

```typescript
const gt = new GT();

const formatted = gt.formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto',
});
// "yesterday"
```

Signature:

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

*Note: `formatRelativeTime` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It uses the instance&#39;s target locale by default, then falls back to the source locale and `en`. For formatting without a `GT` instance, see the standalone [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time).*

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

* **Locale resolution.** When `locales` is omitted, the method uses the instance&#39;s target locale, then the source locale and `en`.
* **Intl-backed.** Formatting is delegated to the browser&#39;s native [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* **Defaults.** `numeric` defaults to `'auto'` (so `-1 day` becomes &quot;yesterday&quot; rather than &quot;1 day ago&quot;) and `style` defaults to `'long'`.

## 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.                                         | `object`                      | Yes      | —       |

### `value` [#value]

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

The relative time value. Negative values are in the past; positive values are in 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**

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 supplementary standard and runtime-specific details.

| Name            | Description                           | Type                            | Optional | Default                                |
| --------------- | ------------------------------------- | ------------------------------- | -------- | -------------------------------------- |
| `locales`       | Locales for formatting.               | `string \| string[]`            | Yes      | `targetLocale` → `sourceLocale` → `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 { GT } from 'generaltranslation';

const gt = new GT();

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

// Future time
gt.formatRelativeTime(3, 'day', { locales: 'fr-FR' });
// Returns: "dans 3 jours"

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

## Notes [#notes]

* Defaults to `numeric: 'auto'` and `style: 'long'`.
* Uses `Intl.RelativeTimeFormat` under the hood.
* To automatically select the unit from a `Date`, use [`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date).