# generaltranslation: General Translation Core SDK: formatMessage
URL: https://generaltranslation.com/zh/docs/core/functions/formatting/format-message.mdx
---
title: formatMessage
description: 独立运行的 formatMessage 函数 API 参考
---

## 概述

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

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

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

***


## 参考

### 参数

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

### 选项对象

| 属性          | 类型                   | 可选 | 默认值      | 描述         |
| ----------- | -------------------- | -- | -------- | ---------- |
| `locales`   | `string \| string[]` | ✓  | `['en']` | 用于格式化的区域设置 |
| `variables` | `FormatVariables`    | ✓  | `{}`     | 包含插值变量的对象  |

### 返回值

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

***

## 行为

### 区域设置处理

* 使用传入的 `locales` 参数进行格式化
* 如果未指定 `locales`，则回退到 `['en']`
* 支持通过数组指定区域设置回退链

### 变量处理

* 简单替换：`{variable}` → 替换为相应的值
* ICU 消息格式：完全支持复数、选择和格式化
* 缺失变量：在输出中保持原样

### 消息格式支持

支持与 GT 类方法相同的 ICU 消息格式特性：

* 数字格式化：`{price, number, currency}`
* 日期格式化：`{date, date, short}`
* 复数形式处理：`{count, plural, ...}`
* 选择：`{gender, select, ...}`

***

## 示例

### 基本用法

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

const greeting = formatMessage('Hello {name}!', {
  locales: ['en'],
  variables: { name: 'World' }
});
console.log(greeting); // "Hello World!"
```


### 不使用 GT 实例

```typescript
// 无需类实例化的格式化工具函数
function quickFormat(template: string, variables: any, 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
// 德语区域设置格式化
const germanPrice = formatMessage('Preis: {price, number, currency}', {
  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');
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"（法语）
console.log(templates.itemCount(5)); // "5 éléments"
```

***


## 说明

* 需要在选项中显式指定区域设置
* 支持与 GT 类方法相同的 ICU 消息格式特性
* 输入模板为空时，返回空字符串
* 变量会先于 ICU 格式化规则处理

## 后续步骤

* 查看 [`Intl.MessageFormat` 文档](https://formatjs.github.io/docs/intl-messageformat/)，了解更多选项
* 使用 GT 类的 [`formatMessage`](/docs/core/class/methods/formatting/format-message) 进行有状态的格式化
* 使用独立的 [`formatNum`](/docs/core/functions/formatting/format-num) 格式化数字
* 了解 `FormatVariables` 类型