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

title: formatMessage
description: 変数とロケールに応じた値で ICU スタイルのメッセージを整形します。formatMessage の API リファレンス。

---

[GT](/docs/platform/core/reference/gt-class/constructor) インスタンスで、変数置換とロケールに応じた書式設定を使ってメッセージを整形します。General Translation は Format.JS の [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) ライブラリを基盤としており、変数の補間、複数形処理、数値や日付フォーマットなど、ICU メッセージ形式のパターンをサポートします。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスで `formatMessage` を呼び出し、メッセージ文字列と、補間する `variables` を含む任意のオプションオブジェクトを渡します。戻り値は、整形済みのメッセージです。

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'fr' });

const formatted = gt.formatMessage('Hello {name}, you have {count} messages', {
  variables: { name: 'Alice', count: 5 },
});
// "Hello Alice, you have 5 messages"
```

シグネチャ:

```typescript
formatMessage(
  message: string,
  options?: {
    locales?: string | string[];
    variables?: FormatVariables;
    dataFormat?: StringFormat;
  }
): string
```

*注: `formatMessage` は `IntlMessageFormat` (`intl-messageformat` 由来) を使用してローカルで実行されるため、APIキーは不要です。`locales` が指定されている場合は、インスタンスのロケールを上書きします。`GT` インスタンスを使わずにフォーマットする場合は、スタンドアロンの [`formatMessage`](/docs/platform/core/reference/utility-functions/formatting/format-message) を参照してください。*

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

* **ICU 処理。** このメソッドは、`IntlMessageFormat` (`intl-messageformat` 由来) を使って ICU message format syntax を解析し、ロケール固有の数値フォーマット、日付フォーマット、通貨のフォーマットを自動的に適用します。
* **ロケールの解決。** `locales` は、その 1 回の呼び出しに限り、インスタンスのデフォルト設定を上書きします。
* **不足している変数はエラーになります。** メッセージ内で参照している変数が `variables` に指定されていない場合、エラーになります。
* **波かっこのエスケープ。** ICU 構文に従い、リテラルの波かっこは単一引用符で囲んでください (`'{'` または `'}'`) 。そうすることで、placeholder の開始として扱われなくなります。

### 変数置換

* シンプルな変数: `{variableName}` は文字列の値に置き換えられます。
* ICU パターン: `{count, plural, ...}` は ICU の書式ルールに従って処理されます。
* 変数が見つからない場合: エラーになります。
* 中括弧をそのまま表示する場合: ICU 構文に従って単一引用符で囲みます (`'{'` または `'}'`)。こうすると、中括弧をそのまま表示できます。

### 対応しているメッセージ形式

* **シンプルな補間:** `{variable}`
* **数値フォーマット:** `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
* **日付フォーマット:** `{date, date, short}`, `{time, time, short}`
* **複数形処理:** `{count, plural, =0 {none} =1 {one} other {many}}`
* **選択:** `{gender, select, male {he} female {she} other {they}}`
* **序数選択:** `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`

## パラメータ [#parameters]

| パラメータ                 | 説明                     | 型        | 任意  | デフォルト |
| --------------------- | ---------------------- | -------- | --- | ----- |
| [`message`](#message) | フォーマットする ICU 形式のメッセージ。 | `string` | いいえ | —     |
| [`options`](#options) | 変数を含むフォーマットの設定。        | `object` | はい  | —     |

### `message` [#message]

**型** `string` · **必須**

ICU message format 構文で記述する、整形対象のメッセージです。

### `options` [#options]

**型** `object` · **任意**

書式設定の構成:

| 名前           | 説明                                                    | 型                    | 任意 | デフォルト       |
| ------------ | ----------------------------------------------------- | -------------------- | -- | ----------- |
| `locales`    | 書式設定に使用するロケール (インスタンスのデフォルトを上書きします) 。                 | `string \| string[]` | はい | インスタンスのロケール |
| `variables`  | メッセージ補間に使用する変数のオブジェクト。                                | `FormatVariables`    | はい | `{}`        |
| `dataFormat` | メッセージ文字列のデータ形式 (`'ICU'`、`'I18NEXT'`、または `'STRING'`) 。 | `StringFormat`       | はい | `'ICU'`     |

`FormatVariables` 型:

```typescript
type FormatVariables = Record<string, string | number | boolean | null | undefined | Date>;
```

## 戻り値 [#returns]

**型** `string`

変数が埋め込まれ、ロケール固有の書式が適用された、整形済みのメッセージです。

## 例 [#examples]

```typescript
// 基本的な変数置換
const gt = new GT({ targetLocale: 'en' });

const message = gt.formatMessage('Welcome {name}!', {
  variables: { name: 'John' },
});
console.log(message); // "Welcome John!"
```

```typescript
// ICU形式による複数形処理
const message = gt.formatMessage(
  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your cart',
  {
    variables: { count: 3 },
  }
);
console.log(message); // "You have 3 items in your cart"
```

```typescript
// 数値と通貨のフォーマット
const gt = new GT({ targetLocale: 'en' });

const message = gt.formatMessage(
  'Your total is {price, number, ::currency/USD} with {discount, number, percent} off',
  {
    variables: {
      price: 99.99,
      discount: 0.15,
    },
  }
);
console.log(message); // "Your total is $99.99 with 15% off"
```

```typescript
// 複雑なメッセージテンプレート
const orderStatusMessage = gt.formatMessage(`
  Order #{orderId} status update:
  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
  - Total: {total, number, ::currency/USD}
  - Status: {status, select,
      pending {Pending}
      shipped {Shipped}
      delivered {Delivered}
      other {Unknown}}
  - Delivery: {deliveryDate, date, short}
`, {
  variables: {
    orderId: 'ORD-12345',
    itemCount: 3,
    total: 149.97,
    status: 'shipped',
    deliveryDate: new Date('2024-03-20'),
  },
});
```

## メモ [#notes]

* このメソッドは、`IntlMessageFormat` (`intl-messageformat`) を使用して ICU message format 構文を処理します。
* 変数が不足している場合はエラーになります。
* ロケール固有の数値フォーマット、日付フォーマット、通貨のフォーマットが自動的に適用されます。
* 単独の数値をフォーマットするには、[`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) を使用します。