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

title: formatMessage
description: GT インスタンスなしで ICU スタイルのメッセージをフォーマットします。formatMessage の API リファレンス。

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) は、General Translation のコアライブラリに含まれるスタンドアロンのユーティリティ関数で、変数置換とロケールに応じた書式設定を使ってメッセージをフォーマットします。ICU message format のパターンに対応しており、変数補間や複数形処理のための主要なツールです。

## 概要 [#overview]

`generaltranslation` から `formatMessage` を直接インポートし、メッセージ文字列とオプションオブジェクトを渡して呼び出します。これには API Key も [GT](/docs/platform/core/reference/gt-class/constructor) インスタンスも必要ありません。インスタンスのロケールを継承する形式で書式設定したい場合は、代わりに [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) メソッドを使用してください。

これは Format.JS の [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) ライブラリをベースにしているため、数値や日付の書式設定、複数形、select にも対応しています。

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

const formatted = formatMessage('Hello {name}, you have {count} messages', {
  locales: ['en'],
  variables: { name: 'Alice', count: 5 },
});
// 戻り値: "Hello Alice, you have 5 messages"
```

シグネチャ:

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

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

* **ロケールの処理。** フォーマットには指定された `locales` を使用し、指定がない場合は `'en'` にフォールバックします。array を指定した場合は、ロケールのフォールバックチェーンとして機能します。
* **変数の処理。** 変数はメッセージ内に置換されます。単純な `{variable}` プレースホルダーは対応する値に置き換えられ、複数形、select、フォーマットについては ICU message format が完全にサポートされています。
* **データ形式。** `dataFormat` のデフォルトは `'ICU'` です。`'STRING'` に設定すると、メッセージは ICU として解析されず、そのまま返されます。
* **メッセージ形式のサポート。** GT class method と同じ ICU 機能が利用できます: 数値のフォーマット (`{price, number, ::currency/USD}`)、日付のフォーマット (`{date, date, short}`)、複数形 (`{count, plural, ...}`)、選択 (`{gender, select, ...}`)。
* **翻訳は行いません。** この関数はメッセージをフォーマットして補間しますが、メッセージ本文自体は翻訳しません。ロケールに応じて変わるのは、変数の値と ICU の出力だけです。

## パラメーター [#parameters]

| パラメーター                | 説明                     | 型        | 任意  | デフォルト |
| --------------------- | ---------------------- | -------- | --- | ----- |
| [`message`](#message) | 書式設定するメッセージ。           | `string` | いいえ | —     |
| [`options`](#options) | 対象ロケールや変数を含む書式設定オプション。 | `object` | はい  | `{}`  |

### `message` [#message]

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

書式設定するメッセージ文字列です。ICU message format のパターンを含めることができます。空文字列を渡すと、空文字列が返されます。

### `options` [#options]

**型** `object` · **任意** · **デフォルト** `{}`

フォーマット設定:

| プロパティ        | 説明                                       | 型                                | 任意 | デフォルト   |
| ------------ | ---------------------------------------- | -------------------------------- | -- | ------- |
| `locales`    | フォーマットに使用するロケール。                         | `string \| string[]`             | はい | `'en'`  |
| `variables`  | 補間に使用する変数を含むオブジェクト。                      | `FormatVariables`                | はい | `{}`    |
| `dataFormat` | メッセージの形式。`'STRING'` の場合、メッセージはそのまま返されます。 | `'ICU' \| 'I18NEXT' \| 'STRING'` | はい | `'ICU'` |

## 戻り値 [#returns]

**型** `string`

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

## 例 [#examples]

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

// 基本的な使い方
const greeting = formatMessage('Hello {name}!', {
  locales: ['en'],
  variables: { name: 'World' },
});
console.log(greeting); // "Hello World!"
```

```typescript
// クラスをインスタンス化せずにフォーマットするユーティリティ関数
function quickFormat(
  template: string,
  variables: Record<string, unknown>,
  locale = 'en'
) {
  return formatMessage(template, {
    locales: [locale],
    variables,
  });
}

const notification = quickFormat(
  'You have {count, plural, =0 {no messages} =1 {one message} other {# messages}}',
  { count: 3 },
  'en'
);
console.log(notification); // "You have 3 messages"
```

```typescript
// 通貨と数値のフォーマット

// ドイツ語ロケールのフォーマット（通貨にはcurrency skeletonが必要）
const germanPrice = formatMessage('Preis: {price, number, ::currency/EUR}', {
  locales: ['de'],
  variables: { price: 1234.56 },
});
console.log(germanPrice); // "Preis: 1.234,56 €"

// パーセント表示のフォーマット
const progress = formatMessage('Progress: {percent, number, percent}', {
  locales: ['en'],
  variables: { percent: 0.85 },
});
console.log(progress); // "Progress: 85%"
```

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

// 再利用可能なメッセージテンプレート
class MessageTemplates {
  private locale: string;

  constructor(locale: string = 'en') {
    this.locale = locale;
  }

  welcome(name: string) {
    return formatMessage('Welcome back, {name}!', {
      locales: [this.locale],
      variables: { name },
    });
  }

  itemCount(count: number) {
    return formatMessage(
      '{count, plural, =0 {No items} =1 {One item} other {# items}}',
      {
        locales: [this.locale],
        variables: { count },
      }
    );
  }
}

const templates = new MessageTemplates('fr');
// 注意: formatMessage はテキストを翻訳しません。ICU の複数形/フォーマットルールのみが
// ロケールに従うため、英語のリテラルテキストはそのまま返されます。
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## メモ [#notes]

* デフォルトロケール以外のロケールでは、options で locale を明示的に指定する必要があります。指定しない場合は `'en'` にフォールバックします。
* GT class method と同じ ICU message format の機能をサポートしています。
* 入力 templates が空の場合は、空の string を返します。
* 変数は ICU の書式設定ルールに従って処理されます。参照されている変数が渡されていない場合は、`MISSING_VALUE` エラーがスローされます。