# generaltranslation: General Translation Core SDK: formatRelativeTime
URL: https://generaltranslation.com/ja/docs/core/functions/formatting/format-relative-time.mdx
---
title: formatRelativeTime
description: ロケールの規則に従って相対時間の値を整形するスタンドアロン関数
---

## 概要

スタンドアロンの`formatRelativeTime`関数は、GT インスタンスを作成しなくても、明示的に指定した単位で相対時間の値をロケール固有の規則に従って整形します。

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

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


## リファレンス

### パラメータ

| 名前        | 型                             | 説明                                                                         |
| --------- | ----------------------------- | -------------------------------------------------------------------------- |
| `value`   | `number`                      | 相対時間の値 (過去は負の値、未来は正の値)                                                     |
| `unit`    | `Intl.RelativeTimeFormatUnit` | 時間単位 (`'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、`'year'`)  |
| `options` | `object`                      | 書式設定のオプション                                                                 |

### オプション

| 名前               | 型                               | 説明                                 |
| ---------------- | ------------------------------- | ---------------------------------- |
| `locales`        | `string \| string[]`            | **必須。** 書式設定に使用するロケール              |
| `numeric?`       | `'always' \| 'auto'`            | 常に数値形式の出力を使用するかどうか。デフォルトは `'auto'` |
| `style?`         | `'long' \| 'short' \| 'narrow'` | 出力の長さ。デフォルトは `'long'`              |
| `localeMatcher?` | `'best fit' \| 'lookup'`        | 使用するロケール照合アルゴリズム                   |

### 戻り値

`string` - 書式設定された相対時間の文字列。

***

## 例

### 基本的な使い方

```typescript copy
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 copy
import { formatRelativeTime } from 'generaltranslation';

// 長いスタイル（デフォルト）
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 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 })}`);
});
// 出力:
// en-US: 3 hours ago
// fr-FR: il y a 3 heures
// ja-JP: 3 時間前
// de-DE: vor 3 Stunden
```

***


## 注記

* デフォルトでは `numeric: 'auto'` と `style: 'long'` が使われます
* `numeric: 'auto'` を指定すると、`-1 day` のような値は "1 day ago" ではなく "yesterday" になります
* 内部的には [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) を使用しています
* 同じロケールとオプションの組み合わせを繰り返し使う場合のパフォーマンス向上のため、結果は内部でキャッシュされます

## 次のステップ

* Date オブジェクトから単位を自動選択するには [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date) を参照してください
* 単体での日付/時刻の書式設定については [`formatDateTime`](/docs/core/functions/formatting/format-date-time) を参照してください
* インスタンスベースで使用する場合は、GT クラスの [`formatRelativeTime`](/docs/core/class/methods/formatting/format-relative-time) を参照してください