# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/it/docs/platform/core/reference/utility-functions/formatting/format-relative-time.mdx
---

title: formatRelativeTime
description: Formatta valori temporali relativi senza un'istanza GT. Riferimento API per formatRelativeTime.

---

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) è una funzione di utilità autonoma della libreria Core di General Translation che formatta un valore temporale relativo con un'unità esplicita, in base alle convenzioni dell'impostazione regionale. Restituisce stringhe come "2 ore fa" o "tra 3 giorni".

## Panoramica [#overview]

Importa `formatRelativeTime` direttamente da `generaltranslation` e chiamalo con un valore, un'unità e un oggetto options. Non richiede una chiave API né un'istanza di [GT](/docs/platform/core/reference/gt-class/constructor). Per la formattazione tramite istanza, che eredita l'impostazione regionale dell'istanza, usa invece il metodo [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) di un'istanza [`GT`](/docs/platform/core/reference/gt-class/constructor). Per selezionare automaticamente l'unità a partire da un `Date`, usa [`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',
});
// Restituisce: "yesterday"
```

Firma:

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

## Come funziona [#how-it-works]

* **API sottostante.** Usa internamente [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* **Convenzione dei segni.** I valori negativi si riferiscono al passato; i valori positivi al futuro.
* **Modalità numerica.** Per impostazione predefinita usa `numeric: 'auto'`, quindi valori come `-1 day` producono &quot;ieri&quot; invece di &quot;1 giorno fa&quot;. Imposta `numeric: 'always'` per forzare un output numerico.
* **Risoluzione dell&#39;impostazione regionale.** Se `locales` viene omesso, viene usata l&#39;impostazione regionale predefinita della libreria, `en`.
* **Caching.** I risultati vengono memorizzati internamente nella cache per migliorare le prestazioni con combinazioni ripetute di impostazione regionale e opzioni.

## Parametri [#parameters]

| Parametro             | Descrizione                                                                            | Tipo                                                                                 | Facoltativo | Predefinito |
| --------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------- | ----------- |
| [`value`](#value)     | Il valore temporale relativo (negativo per il passato, positivo per il futuro).        | `number`                                                                             | No          | —           |
| [`unit`](#unit)       | L&#39;unità di tempo.                                                                  | `Intl.RelativeTimeFormatUnit`                                                        | No          | —           |
| [`options`](#options) | Configurazione della formattazione, incluse le impostazioni regionali di destinazione. | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | Sì          | `{}`        |

### `value` [#value]

**Tipo** `number` · **Obbligatorio**

Il valore temporale relativo. I numeri negativi indicano il passato, quelli positivi il futuro.

### `unit` [#unit]

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

L&#39;unità di tempo: `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'` o `'year'`.

### `options` [#options]

**Tipo** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **Facoltativo** · **Predefinito** `{}`

Configurazione della formattazione:

| Proprietà       | Descrizione                                                                  | Tipo                            | Facoltativo | Predefinito  |
| --------------- | ---------------------------------------------------------------------------- | ------------------------------- | ----------- | ------------ |
| `locales`       | Impostazioni regionali per la formattazione.                                 | `string \| string[]`            | Sì          | `en`         |
| `numeric`       | Se usare sempre valori numerici nell&#39;output.                             | `'always' \| 'auto'`            | Sì          | `'auto'`     |
| `style`         | La lunghezza dell&#39;output.                                                | `'long' \| 'short' \| 'narrow'` | Sì          | `'long'`     |
| `localeMatcher` | L&#39;algoritmo da usare per la corrispondenza delle impostazioni regionali. | `'best fit' \| 'lookup'`        | Sì          | `'best fit'` |

## Returns [#returns]

**Type** `string`

La stringa formattata del tempo relativo.

## Esempi [#examples]

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

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

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

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

```typescript
// Stili di formattazione

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

// Stile breve
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'short',
}));
// Output: "2 days ago" (può essere abbreviato in alcune impostazioni regionali)

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

```typescript
// Più impostazioni regionali
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
```

## Note [#notes]

* Il valore predefinito è `numeric: 'auto'` e `style: 'long'`.
* Con `numeric: 'auto'`, valori come `-1 day` producono &quot;ieri&quot; invece di &quot;1 giorno fa&quot;.
* Si basa su [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).
* I risultati vengono memorizzati nella cache per migliorare le prestazioni quando si ripetono le stesse combinazioni di impostazione regionale e opzioni.