# generaltranslation: General Translation Core SDK: formatMessage
URL: https://generaltranslation.com/zh/docs/core/class/methods/formatting/format-message.mdx
---
title: formatMessage
description: GT formatMessage 方法的 API 参考文档
---

## 概述

`formatMessage` 方法用于格式化消息，支持变量替换和基于区域设置的格式化。
它基于 Format.JS 的 [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) 库，并支持 ICU 消息格式模式。

该方法对于变量插值和复数形式处理至关重要。
此外，它还支持数字格式化、日期格式化等功能。

```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"
```

***


## 参考

### 参数

<TypeTable
  type={{
  "message": {
    type: 'string',
    optional: false,
  },
  "options?": {
    type: 'object',
    optional: true,
  }
}}
/>

### 选项对象

| 属性           | 类型                   | 可选 | 描述                                              |
| ------------ | -------------------- | -- | ----------------------------------------------- |
| `locales`    | `string \| string[]` | ✓  | 用于格式化的区域设置 (会覆盖实例默认值)                           |
| `variables`  | `FormatVariables`    | ✓  | 包含用于消息插值的变量的对象                                  |
| `dataFormat` | `StringFormat`       | ✓  | 消息字符串的数据格式 (例如，`'ICU'`、`'I18NEXT'`、`'STRING'`)  |

### FormatVariables 类型

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

### 返回值

`string` - 已替换变量并应用特定于区域设置格式的消息。

***

## 行为

### 变量替换

* 简单变量：`{variableName}` → 替换为字符串
* ICU 模式：`{count, plural, ...}` → 按 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}}`

***

## 示例

### 基本变量替换

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

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


### 使用 ICU 格式处理复数

```typescript
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); // "您的购物车中有 3 件商品"
```


### 数字和货币格式设置

```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); // "您的总计为 $99.99，享受 15% 折扣"
```


### 复杂消息模板

```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')
  }
});
```

***


## 说明

* 该方法使用 Format.JS 的 [`Intl.MessageFormat`](https://formatjs.github.io/docs/intl-messageformat/) 处理 ICU 消息格式语法，以支持高级格式化。
* 缺失变量时会报错。
* 会自动应用特定于区域设置的数字、日期和货币格式

## 后续步骤

* 查阅 [`Intl.MessageFormat` 文档](https://formatjs.github.io/docs/intl-messageformat/)，了解更多选项
* 使用 [formatNum](/docs/core/class/methods/formatting/format-num) 格式化数字