# generaltranslation: General Translation Core SDK: formatRelativeTime
URL: https://generaltranslation.com/en-US/docs/core/functions/formatting/format-relative-time.mdx
---
title: formatRelativeTime
description: Standalone function to format relative time values according to locale conventions
---

## Overview

The standalone `formatRelativeTime` function formats a relative time value with an explicit unit, according to locale-specific conventions without requiring a GT instance.

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

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

## Reference

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `value` | `number` | The relative time value (negative for past, positive for future) |
| `unit` | `Intl.RelativeTimeFormatUnit` | The unit of time (`'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`) |
| `options` | `object` | Formatting configuration |

### Options

| Name | Type | Description |
|------|------|-------------|
| `locales` | `string \| string[]` | **Required.** Locales for formatting |
| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output. Defaults to `'auto'` |
| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output. Defaults to `'long'` |
| `localeMatcher?` | `'best fit' \| 'lookup'` | The locale matching algorithm to use |

### Returns

`string` - The formatted relative time string.

---

## Example

### Basic usage

```typescript copy
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"
```

### Formatting styles

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

// 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"
```

### Multiple locales

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

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

* 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

## Next steps

* See [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date) for auto-selecting the unit from a Date
* See [`formatDateTime`](/docs/core/functions/formatting/format-date-time) for standalone date/time formatting
* See GT class [`formatRelativeTime`](/docs/core/class/methods/formatting/format-relative-time) for instance-based usage