# General Translation Platform: formatMessage
URL: https://generaltranslation.com/zh/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 Core 核心库提供的一个独立工具函数，用于通过变量替换和基于区域设置的格式设置来格式化消息。它支持 ICU 消息格式 模式，因此是进行变量插值和复数形式处理的主要工具。

## 概览 [#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/) 库构建，因此也支持数字格式化、日期格式化、复数和选择。

```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'`。数组会作为区域设置的后备链。
* **变量处理。** 变量会被代入消息中。简单的 `{variable}` 占位符会替换为对应的值；同时完全支持 ICU 消息格式中的复数、选择和格式化。
* **数据格式。** `dataFormat` 默认为 `'ICU'`。当设为 `'STRING'` 时，消息会按原样返回，不会进行 ICU 解析。
* **消息格式支持。** 支持与 GT 类方法 相同的 ICU 功能：数字格式化 (`{price, number, ::currency/USD}`) 、日期格式化 (`{date, date, short}`) 、复数处理 (`{count, plural, ...}`) 以及选择 (`{gender, select, ...}`) 。
* **不进行翻译。** 此函数只会对消息进行格式化和插值，不会翻译消息文本本身。只有变量值和 ICU 输出会根据区域设置进行调整。

## 参数 [#parameters]

| 参数                    | 描述                 | 类型       | 可选 | 默认值  |
| --------------------- | ------------------ | -------- | -- | ---- |
| [`message`](#message) | 待格式化的消息。           | `string` | 否  | —    |
| [`options`](#options) | 格式化配置，包括目标区域设置和变量。 | `object` | 是  | `{}` |

### `message` [#message]

**Type** `string` · **必填**

要格式化的消息字符串。可以包含 ICU 消息格式 模式。空字符串会返回空字符串。

### `options` [#options]

**Type** `object` · **可选** · **默认值** `{}`

格式化配置：

| Property     | Description                    | Type                             | Optional | Default |
| ------------ | ------------------------------ | -------------------------------- | -------- | ------- |
| `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
// 货币和数字格式化

// 德语区域设置格式化（货币需要货币 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]

* 对于非默认区域设置，需要在选项中显式指定区域设置；否则会回退到 `'en'`。
* 支持与 GT 类方法相同的 ICU 消息格式功能。
* 对于空输入模板，返回空字符串。
* 变量会按照 ICU 格式化规则处理；如果引用了未提供的变量，则会抛出 `MISSING_VALUE` 错误。