# gt-next: General Translation Next.js SDK: RelativeTime
URL: https://generaltranslation.com/ja/docs/next/api/components/relativetime.mdx
---
title: RelativeTime
description: RelativeTime コンポーネントの API リファレンス
---

{/* 自動生成: 直接編集しないでください。代わりに content/docs-templates/ 内のテンプレートを編集してください。 */}


## 概要

`<RelativeTime>` コンポーネントは、&quot;2時間前&quot; や &quot;3日後&quot; のような、ローカライズされた相対時間の文字列をレンダリングします。
使用方法は 2 つあります。`Date` から最適な単位を自動的に選択する方法と、値と単位を明示的に指定する方法です。

```jsx
<RelativeTime>{someDate}</RelativeTime>
// 出力: "2 hours ago"
```

すべての書式設定は、[`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) API を使ってローカルで行われます。

<Callout type="warn">
  `<RelativeTime>` は、サーバーでレンダリングされるアプリで **React のハイドレーションエラー** を引き起こすことがあります。詳しくは、以下の[ハイドレーションエラーの回避](#avoiding-hydration-errors)を参照してください。
</Callout>

## リファレンス

### プロパティ

<TypeTable
  type={{
  "children?": {
      description: '相対時間の計算元となる Date オブジェクトです。',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "date?": {
      description: '相対時間の計算元となる Date オブジェクトです。children より優先されます。',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "value?": {
      description: '相対時間の数値を明示的に指定します。unit が必要です。',
      type: 'number',
      optional: true,
      default: 'undefined',
  },
  "unit?": {
      description: '時間の単位です。value を使用する場合に必須です。',
      type: 'Intl.RelativeTimeFormatUnit',
      optional: true,
      default: 'undefined',
  },
  "baseDate?": {
      description: '相対時間を計算する基準日です。デフォルトはレンダリング時の new Date() です。',
      type: 'Date',
      optional: true,
      default: 'new Date()',
  },
  "name?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
  "options?": {
      type: 'Intl.RelativeTimeFormatOptions',
      optional: true,
      default: "{ numeric: 'auto', style: 'long' }",
  },
  "locales?": {
      type: 'string[]',
      optional: true,
      default: 'undefined',
  },
}}
/>

### 説明

| Prop 名     | 説明                                                                                                                                                                                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `Date` オブジェクトです。コンポーネントは最適な単位 (秒、分、時間、日、週、月、または年) を自動的に選択し、`baseDate` を基準とした相対時間として時刻を書式設定します。                                                                                                                  |
| `date`     | 相対時間の計算元となる `Date` オブジェクトです。`date` と `children` の両方が指定されている場合は、`date` が優先されます。                                                                                                                                  |
| `value`    | 相対時間を表す明示的な数値です (例: 「昨日」を表す `-1`) 。`unit` とあわせて使用する必要があります。                                                                                                                                                     |
| `unit`     | 時間の単位です (例: `'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、`'year'`) 。`value` を使用する場合は必須です。                                                                                                          |
| `baseDate` | 相対時間を計算する基準日です。デフォルトはレンダー時の `new Date()` です。**ハイドレーションエラーを避けるため、これを明示的に設定してください** — 詳しくは[以下](#avoiding-hydration-errors)を参照してください。                                                                              |
| `options`  | [`Intl.RelativeTimeFormatOptions` 仕様](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)に従う任意の書式設定オプションです。デフォルトは `numeric: 'auto'` と `style: 'long'` です。 |
| `locales`  | 書式設定に使用するロケールを指定するための任意の `locales` です。指定しない場合は、ユーザーのロケールが使用されます。ロケールの指定方法について詳しくは[こちら](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)を参照してください。        |

### 戻り値

書式設定された相対時刻を表す `string` を含む `JSX.Element`。日付または値が指定されていない場合は `null`。

***

## 例

### `Date` から単位を自動で選択

`Date` を子要素として渡すと、コンポーネントが最適な単位を自動で選択します。

```jsx title="PostTimestamp.jsx" copy
import { RelativeTime } from 'gt-next';

export default function PostTimestamp({ post }) {
    return (
        <RelativeTime>{post.createdAt}</RelativeTime> // [!code highlight]
    );
    // 出力例: "2 hours ago"、"3 days ago"、"in 5 minutes" など
}
```


### `date` プロパティを使う

`children` の代わりに、`date` プロパティで日付を渡すこともできます。

```jsx title="PostTimestamp.jsx" copy
import { RelativeTime } from 'gt-next';

export default function PostTimestamp({ post }) {
    return (
        <RelativeTime date={post.createdAt} /> // [!code highlight]
    );
}
```


### 明示的な値と単位

`Intl.RelativeTimeFormat` API と同様に、値と単位を明示的に指定します。

```jsx title="Reminder.jsx" copy
import { RelativeTime } from 'gt-next';

export default function Reminder() {
    return (
        <p>
            Your trial ends <RelativeTime value={3} unit="day" />. // [!code highlight]
        </p>
    );
    // 出力: "Your trial ends in 3 days."
}
```


### ロケールを指定する

特定のロケールで相対時間を表示します。

```jsx title="FrenchTimestamp.jsx" copy
import { RelativeTime } from 'gt-next';

export default function FrenchTimestamp({ date }) {
    return (
        <RelativeTime locales={['fr-FR']}>{date}</RelativeTime> // [!code highlight]
    );
    // 出力: "il y a 2 heures"
}
```


### RelativeTime を翻訳する

`<RelativeTime>` を `<T>` コンポーネントで囲むと、翻訳文の中に含められます。

```jsx title="Comment.jsx" copy
import { T, RelativeTime } from 'gt-next';

export default function Comment({ comment }) {
    return (
        <T id="commentPosted">
            Posted <RelativeTime>{comment.createdAt}</RelativeTime> // [!code highlight]
        </T>
    );
}
```


### カスタム書式設定オプション

`Intl.RelativeTimeFormat` のオプションで出力スタイルを制御できます。

```jsx title="NumericTimestamp.jsx" copy
import { RelativeTime } from 'gt-next';

export default function NumericTimestamp({ date }) {
    return (
        <RelativeTime
            options={{
                numeric: 'always', // [!code highlight]
                style: 'narrow', // [!code highlight]
            }}
        >
            {date}
        </RelativeTime>
    );
    // numeric: 'always' を指定すると、"yesterday" の代わりに "1 day ago" と出力される
}
```

***


## ハイドレーションエラーを回避する

`<RelativeTime>` は相対時間をローカルで計算するため、**サーバーとクライアントで出力が異なる**ことがあります。React がサーバーで render された HTML とクライアント側の render 結果を比較したときに一致しないと、ハイドレーションエラーが発生します。

これは通常、次のような場合に起こります。

* **`baseDate` が render 時点の `new Date()` をデフォルト値として使用している場合。** サーバーはある時点で render され、その数秒後 (あるいはそれ以上後) にクライアントでハイドレーションされます。この 2 つの時点の間に相対時間が単位の切り替わりをまたぐと (例: &quot;59 seconds ago&quot; → &quot;1 minute ago&quot;) 、出力が一致しなくなります。
* **環境ごとにデフォルトロケールが異なる場合。** サーバーのデフォルトロケールがクライアントと一致しないと、書式設定された文字列が異なることがあります (例: &quot;hace 2 horas&quot; vs &quot;2 hours ago&quot;) 。

### 修正方法

サーバーとクライアントで同じ相対時刻を算出できるよう、**`baseDate` を明示的に設定します**：

```jsx
const now = new Date(); // 一度だけ計算し、サーバーとクライアントの両方に渡す

<RelativeTime baseDate={now}>{post.createdAt}</RelativeTime>
```

**`locales` を明示的に指定**して、ロケールの不一致を防いでください:

```jsx
<RelativeTime locales={['en-US']} baseDate={now}>
  {post.createdAt}
</RelativeTime>
```

ロケールと基準日付の両方を固定すると、サーバーとクライアントは常に同じ書式設定済みの文字列を生成します。


## 注意事項

* `<RelativeTime>` コンポーネントは、相対時間を表す値を書式設定する変数コンポーネントです。
* auto モード (`Date` を使用) では、コンポーネントが最も適切な単位を自動で選択します。
* このコンポーネントは内部で [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) を使用しています。
* デフォルトの書式設定オプションは `numeric: 'auto'` と `style: 'long'` です。

## 次のステップ

* `<RelativeTime>` コンポーネントや、`<DateTime>`、`<Currency>`、`<Num>`、`<Var>` などの変数コンポーネントの詳細や使用例については、[変数コンポーネントの使用](/docs/next/guides/variables)のドキュメントを参照してください。