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

title: formatRelativeTime
description: GT インスタンスなしで相対時間値をフォーマットします。formatRelativeTime の API リファレンス。

---

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) は、General Translation のコアライブラリに含まれるスタンドアロンのユーティリティ関数で、明示的な単位を指定して、ロケール固有の規則に従い相対時間値をフォーマットします。戻り値は、「2時間前」や「3日後」のような文字列です。

## 概要 [#overview]

`generaltranslation` から `formatRelativeTime` を直接インポートし、値、単位、オプションオブジェクトを指定して呼び出します。API Key や [GT](/docs/platform/core/reference/gt-class/constructor) インスタンスは不要です。インスタンスのロケールを継承するインスタンスベースのフォーマットを行う場合は、代わりに [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) メソッドを使用してください。`Date` から単位を自動選択するには、[`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',
});
// 戻り値: "yesterday"
```

シグネチャ:

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

## 仕組み [#how-it-works]

* **基盤となる API。** 内部では [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) を使用します。
* **符号規則。** 負の値は過去、正の値は未来を表します。
* **数値モード。** デフォルトでは `numeric: 'auto'` が使われるため、`-1 day` のような値は &quot;1 day ago&quot; ではなく「yesterday」になります。数値での出力を常に行うには、`numeric: 'always'` を設定してください。
* **ロケールの解決。** `locales` を省略すると、ライブラリのデフォルトロケールである `en` が使われます。
* **キャッシュ。** パフォーマンス向上のため、同じロケールとオプションの組み合わせに対する結果は内部でキャッシュされます。

## パラメータ [#parameters]

| パラメータ                 | 説明                         | 型                                                                                    | 任意  | デフォルト |
| --------------------- | -------------------------- | ------------------------------------------------------------------------------------ | --- | ----- |
| [`value`](#value)     | 相対時間の値 (過去は負の値、未来は正の値) 。   | `number`                                                                             | いいえ | —     |
| [`unit`](#unit)       | 時間の単位。                     | `Intl.RelativeTimeFormatUnit`                                                        | いいえ | —     |
| [`options`](#options) | target ロケール を含むフォーマット設定。 | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | はい  | `{}`  |

### `value` [#value]

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

相対時間の値です。負の数は過去、正の数は未来を表します。

### `unit` [#unit]

**型** `Intl.RelativeTimeFormatUnit` · **必須**

時間単位: `'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、または `'year'`。

### `options` [#options]

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

フォーマット設定:

| Property        | Description         | Type                            | Optional | Default      |
| --------------- | ------------------- | ------------------------------- | -------- | ------------ |
| `locales`       | フォーマットに使用するロケール。    | `string \| string[]`            | Yes      | `en`         |
| `numeric`       | 常に数値による出力を使用するかどうか。 | `'always' \| 'auto'`            | Yes      | `'auto'`     |
| `style`         | 出力表記の長さ。            | `'long' \| 'short' \| 'narrow'` | Yes      | `'long'`     |
| `localeMatcher` | 使用するロケール照合アルゴリズム。   | `'best fit' \| 'lookup'`        | Yes      | `'best fit'` |

## 戻り値 [#returns]

**型** `string`

フォーマット済みの相対時間文字列。

## 例 [#examples]

```typescript
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
// フォーマットスタイル

// ロングスタイル（デフォルト）
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
// 複数のロケール
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
```

## メモ [#notes]

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