# generaltranslation: General Translation Core SDK: formatMessage
URL: https://generaltranslation.com/en-US/docs/core/class/methods/formatting/format-message.mdx
---
title: formatMessage
description: API reference for the GT formatMessage method
---

## Overview

The `formatMessage` method formats messages with variable substitution and locale-aware formatting.
Built on top of Format.JS's [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) library, it supports ICU message format patterns.

This method is essential for variable interpolation and pluralization.
It also supports number formatting and date formatting among other features.

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

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

---

## Reference

### Parameters

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

### Options object

| Property | Type | Optional | Description |
|----------|------|----------|-------------|
| `locales` | `string \| string[]` | ✓ | Locale(s) to use for formatting (overrides instance defaults) |
| `variables` | `FormatVariables` | ✓ | Object containing variables for message interpolation |
| `dataFormat` | `StringFormat` | ✓ | Data format of the message string (e.g., `'ICU'`, `'I18NEXT'`, `'STRING'`) |

### FormatVariables type

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

### Returns

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

---

## Behavior


### Variable substitution

- Simple variables: `{variableName}` → replaced with string value
- ICU patterns: `{count, plural, ...}` → processed with ICU formatting rules
- Missing variables: will result in an error
- Double curly braces: will escape the curly brace behavior and render as a single curly brace

### Message format support

- **Simple interpolation**: `{variable}`
- **Number formatting**: `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
- **Date formatting**: `{date, date, short}`, `{time, time, short}`
- **Pluralization**: `{count, plural, =0 {none} =1 {one} other {many}}`
- **Selection**: `{gender, select, male {he} female {she} other {they}}`
- **Selectordinal**: `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`

---

## Examples

### Basic variable substitution

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

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

### Pluralization with ICU format

```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); // "You have 3 items in your cart"
```

### Number and currency formatting

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

### Complex message templates

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

- The method processes ICU message format syntax for advanced formatting using [`Intl.MessageFormat`](https://formatjs.github.io/docs/intl-messageformat/) from Format.JS.
- Missing variables will throw an error.
- Locale-specific number, date, and currency formatting is applied automatically

## Next steps

- Check out [`Intl.MessageFormat` documentation](https://formatjs.github.io/docs/intl-messageformat/) for more options
- Format numbers with [formatNum](/docs/core/class/methods/formatting/format-num)