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

title: formatMessage
description: Форматируйте сообщения в формате ICU без экземпляра GT. Справочник API для formatMessage.

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) — это отдельная вспомогательная функция из библиотеки Core от General Translation, которая форматирует сообщения с подстановкой переменных и с учетом локали. Она поддерживает шаблоны ICU MessageFormat, поэтому это основной инструмент для интерполяции переменных и плюрализации.

## Обзор [#overview]

Импортируйте `formatMessage` напрямую из `generaltranslation` и вызовите его, передав строку сообщения и объект параметров. Для этого не требуется API-ключ или экземпляр [GT](/docs/platform/core/reference/gt-class/constructor). Если вам нужно форматирование через экземпляр с наследованием его локали, используйте вместо этого метод [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor).

Он построен на основе библиотеки [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) от Format.JS, поэтому также поддерживает форматирование чисел, дат, формы множественного числа и конструкции `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'`. Массивы образуют цепочку резервных локалей.
* **Обработка переменных.** Переменные подставляются в сообщение. Простые плейсхолдеры `{variable}` заменяются их значениями; ICU MessageFormat полностью поддерживает множественное число, выбор и форматирование.
* **Формат данных.** По умолчанию `dataFormat` имеет значение `'ICU'`. Если задано `'STRING'`, сообщение возвращается как есть, без разбора ICU.
* **Поддержка формата сообщений.** Доступны те же возможности ICU, что и у метода класса GT: форматирование чисел (`{price, number, ::currency/USD}`), форматирование дат (`{date, date, short}`), плюрализация (`{count, plural, ...}`) и выбор (`{gender, select, ...}`).
* **Без перевода.** Эта функция форматирует сообщение и подставляет значения; сам текст сообщения она не переводит. К локали адаптируются только значения переменных и вывод ICU.

## Параметры [#parameters]

| Параметр              | Описание                                                                    | Тип      | Необязательный | По умолчанию |
| --------------------- | --------------------------------------------------------------------------- | -------- | -------------- | ------------ |
| [`message`](#message) | Сообщение, которое нужно форматировать.                                     | `string` | Нет            | —            |
| [`options`](#options) | Параметры форматирования, включая целевую локаль (или локали) и переменные. | `object` | Да             | `{}`         |

### `message` [#message]

**Тип** `string` · **Обязательно**

Строка сообщения, которую нужно отформатировать. Может содержать шаблоны в формате ICU MessageFormat. Пустая строка возвращает пустую строку.

### `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
// Форматирование валюты и чисел

// Форматирование для немецкой локали (для валюты требуется 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 plural/format
// зависят от локали, поэтому исходный английский текст возвращается без изменений.
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## Заметки [#notes]

* Для локалей, отличных от локали по умолчанию, нужно явно указать локаль в `options`; иначе используется `'en'`.
* Поддерживает те же возможности ICU MessageFormat, что и метод класса GT.
* Для пустых входных шаблонов возвращает пустую строку.
* Переменные обрабатываются по правилам форматирования ICU; если переменная указана, но не передана, возникает ошибка `MISSING_VALUE`.