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

title: formatMessage
description: Format ICU-style messages without a GT instance. API reference for formatMessage.

---

[`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) is a standalone utility function from General Translation's Core library that formats messages with variable substitution and locale-aware formatting. It supports ICU message format patterns, making it the primary tool for variable interpolation and pluralization.

## Overview [#overview]

Import `formatMessage` directly from `generaltranslation` and call it with a message string and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based formatting that inherits the instance locale, use the [`formatMessage`](/docs/platform/core/reference/gt-class-methods/formatting/format-message) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

It is built on top of Format.JS's [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) library, so it also supports number formatting, date formatting, plurals, and selects.

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

const formatted = formatMessage('Hello {name}, you have {count} messages', {
  locales: ['en'],
  variables: { name: 'Alice', count: 5 },
});
// Returns: "Hello Alice, you have 5 messages"
```

Signature:

```typescript
formatMessage(
  message: string,
  options?: {
    locales?: string | string[];
    variables?: FormatVariables;
    dataFormat?: 'ICU' | 'I18NEXT' | 'STRING';
  }
): string
```

## How it works [#how-it-works]

- **Locale handling.** Uses the provided `locales` for formatting, falling back to `'en'` when none are specified. Arrays act as a locale fallback chain.
- **Variable processing.** Variables are substituted into the message. Simple `{variable}` placeholders are replaced with their values; ICU message format is fully supported for plurals, selects, and formatting.
- **Data format.** `dataFormat` defaults to `'ICU'`. When set to `'STRING'`, the message is returned as-is without ICU parsing.
- **Message format support.** The same ICU features as the GT class method are available: number formatting (`{price, number, ::currency/USD}`), date formatting (`{date, date, short}`), pluralization (`{count, plural, ...}`), and selection (`{gender, select, ...}`).
- **No translation.** This function formats and interpolates a message; it does not translate the message text itself. Only the variable values and ICU output adapt to the locale.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`message`](#message) | The message to format. | `string` | No | — |
| [`options`](#options) | Formatting configuration, including the target locale(s) and variables. | `object` | Yes | `{}` |

### `message` [#message]

**Type** `string` · **Required**

The message string to format. May contain ICU message format patterns. An empty string returns an empty string.

### `options` [#options]

**Type** `object` · **Optional** · **Default** `{}`

Formatting configuration:

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Locale(s) to use for formatting. | `string \| string[]` | Yes | `'en'` |
| `variables` | Object containing variables for interpolation. | `FormatVariables` | Yes | `{}` |
| `dataFormat` | The format of the message. When `'STRING'`, the message is returned as-is. | `'ICU' \| 'I18NEXT' \| 'STRING'` | Yes | `'ICU'` |

## Returns [#returns]

**Type** `string`

The formatted message with variables substituted and locale-specific formatting applied.

## Examples [#examples]

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

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

```typescript
// Utility function for formatting without class instantiation
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
// Currency and number formatting

// German locale formatting (currency requires a currency skeleton)
const germanPrice = formatMessage('Preis: {price, number, ::currency/EUR}', {
  locales: ['de'],
  variables: { price: 1234.56 },
});
console.log(germanPrice); // "Preis: 1.234,56 €"

// Percentage formatting
const progress = formatMessage('Progress: {percent, number, percent}', {
  locales: ['en'],
  variables: { percent: 0.85 },
});
console.log(progress); // "Progress: 85%"
```

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

// Reusable message templates
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');
// Note: formatMessage does not translate text — only ICU plural/format rules
// follow the locale, so the literal English text is returned as written.
console.log(templates.welcome('Marie')); // "Welcome back, Marie!"
console.log(templates.itemCount(5)); // "5 items"
```

## Notes [#notes]

- Requires explicit locale specification in options for non-default locales; otherwise falls back to `'en'`.
- Supports the same ICU message format features as the GT class method.
- Returns an empty string for empty input templates.
- Variables are processed according to ICU formatting rules; a referenced variable that is not supplied throws a `MISSING_VALUE` error.