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

title: formatRelativeTime
description: 数分前や数日後のような相対時間の値をフォーマットします。formatRelativeTime の API リファレンス。

---

[GT](/docs/platform/core/reference/gt-class/constructor) インスタンス上で、明示的な単位を持つ相対時間の値を、ロケール固有の規則に従ってフォーマットします。General Translation は組み込みの `Intl.RelativeTimeFormat` API を使用して、「2 時間前」や「3 日後」のような表現を生成します。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスで `formatRelativeTime` を呼び出すには、数値、時間の単位、必要に応じて options object を指定します。負の値は過去、正の値は未来を表します。戻り値は、フォーマット済み文字列です。

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

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

シグネチャ:

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

*注: `formatRelativeTime` は `Intl.RelativeTimeFormat` を使用してローカルで動作するため、API キーは不要です。デフォルトではインスタンスの対象ロケールを使用し、次にソースロケール、`en` の順にフォールバックします。`GT` インスタンスなしで書式設定する場合は、スタンドアロンの [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time) を参照してください。*

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

* **ロケールの解決。** `locales` が省略されている場合、このメソッドはインスタンスの対象ロケール、次にソースロケール、最後に `en` を使用します。
* **Intl ベース。** フォーマットは、ブラウザネイティブの [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) に委ねられます。
* **デフォルト。** `numeric` のデフォルトは `'auto'` (そのため `-1 day` は &quot;1 日前&quot; ではなく「昨日」になります) で、`style` のデフォルトは `'long'` です。

## パラメータ [#parameters]

| パラメータ                 | 説明                   | 型                             | 省略可能 | デフォルト |
| --------------------- | -------------------- | ----------------------------- | ---- | ----- |
| [`value`](#value)     | 相対時間の値 (過去は負、未来は正) 。 | `number`                      | いいえ  | —     |
| [`unit`](#unit)       | 時間の単位。               | `Intl.RelativeTimeFormatUnit` | いいえ  | —     |
| [`options`](#options) | 書式設定。                | `object`                      | はい   | —     |

### `value` [#value]

**型** `number` · **必須**

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

### `unit` [#unit]

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

時間の単位。単数形と複数形のどちらも指定できます。`'second'`/`'seconds'`、`'minute'`/`'minutes'`、`'hour'`/`'hours'`、`'day'`/`'days'`、`'week'`/`'weeks'`、`'month'`/`'months'`、`'quarter'`/`'quarters'`、または `'year'`/`'years'`。

### `options` [#options]

**型** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **任意**

フォーマット設定。表には、公開されているCore型で利用可能な一般的なオプションと、実際に適用されるCoreのデフォルト値を示します。補足的な標準仕様およびランタイム固有の詳細については、[`Intl.RelativeTimeFormat` コンストラクターオプション](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)を参照してください。

| 名前              | 説明                  | 型                               | 任意 | デフォルト                                  |
| --------------- | ------------------- | ------------------------------- | -- | -------------------------------------- |
| `locales`       | フォーマットに使用するロケール。    | `string \| string[]`            | はい | `targetLocale` → `sourceLocale` → `en` |
| `numeric`       | 常に数値形式の出力を使用するかどうか。 | `'always' \| 'auto'`            | はい | `'auto'`                               |
| `style`         | 出力の長さ。              | `'long' \| 'short' \| 'narrow'` | はい | `'long'`                               |
| `localeMatcher` | 使用するロケール照合アルゴリズム。   | `'best fit' \| 'lookup'`        | はい | `'best fit'`                           |

Coreでは、上流の`numeric`のデフォルトを`'always'`から`'auto'`に変更しています。その他の標準デフォルトは`Intl.RelativeTimeFormat`に由来します。

## 戻り値 [#returns]

**型** `string`

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

## 例 [#examples]

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

const gt = new GT();

// 過去の時間
gt.formatRelativeTime(-2, 'hour', { locales: 'en-US' });
// 戻り値: "2 hours ago"

// 未来の時間
gt.formatRelativeTime(3, 'day', { locales: 'fr-FR' });
// 戻り値: "dans 3 jours"

// numeric: 'auto' を使用（デフォルト）
gt.formatRelativeTime(-1, 'day', { locales: 'en-US' });
// 戻り値: "yesterday"
```

## メモ [#notes]

* デフォルトは `numeric: 'auto'` と `style: 'long'` です。
* 内部では `Intl.RelativeTimeFormat` を使用します。
* `Date` から `unit` を自動的に選択するには、[`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date) を使用します。