# General Translation Platform: formatMessage
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/formatting/format-message.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Форматируйте сообщения в стиле ICU с переменными и значениями с учетом локали. Справочник по API для formatMessage.

Форматирует сообщение с подстановкой переменных и форматированием с учетом локали в экземпляре [GT](/docs/platform/core/reference/gt-class/constructor). Нативный ICU-форматтер General Translation поддерживает интерполяцию переменных, плюрализацию, форматирование чисел и дат.

## Обзор [#overview]

Вызовите `formatMessage` у экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), передав строку сообщения и необязательный объект параметров с `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` работает локально и не требует API-ключа. Если передан `locales`, он переопределяет локали экземпляра. О форматировании без экземпляра `GT` см. в автономной версии [`formatMessage`](/docs/platform/core/reference/utility-functions/formatting/format-message).*

## Как это работает [#how-it-works]

* **Обработка ICU.** Метод использует нативный ICU-форматтер General Translation и автоматически применяет форматирование чисел, дат и валют в соответствии с локалью.
* **Определение локали.** `locales` переопределяет значения экземпляра по умолчанию для одного вызова.
* **Отсутствующие переменные выбрасывают исключение.** Если в сообщении есть переменная, которая не передана в `variables`, выбрасывается исключение.
* **Экранирование фигурных скобок.** В соответствии с синтаксисом ICU заключайте фигурную скобку в одинарные кавычки (`'{'` или `'}'`), чтобы она не воспринималась как начало плейсхолдера.

### Подстановка переменных

* Простые переменные: `{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 MessageFormat.

### `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]

* Метод обрабатывает синтаксис ICU MessageFormat с помощью встроенного форматтера General Translation.
* Если переменные отсутствуют, выбрасывается исключение.
* Форматирование чисел, дат и валюты в соответствии с локалью применяется автоматически.
* Чтобы форматировать отдельные числа, используйте [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num).

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.