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

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


---

## Reference

### Parameters

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

### Options object

| Property | Type | Optional | Default | Description |
|----------|------|----------|---------|-------------|
| `locales` | `string \| string[]` | ✓ | `['en']` | Locale(s) to use for formatting |
| `variables` | `FormatVariables` | ✓ | `{}` | Object containing variables for interpolation |

### Returns

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

---

## Behavior

### Locale handling

- Uses provided `locales` parameter for formatting
- Falls back to `['en']` if no locales specified
- Supports locale fallback chains with arrays

### Variable processing

- Simple substitution: `{variable}` → replaced with value
- ICU message format: Full support for plurals, selects, and formatting
- Missing variables: Left unchanged in output

### Message format support

Same ICU message format features as the GT class method:
- Number formatting: `{price, number, currency}`
- Date formatting: `{date, date, short}`
- Pluralization: `{count, plural, ...}`
- Selection: `{gender, select, ...}`

---

## Examples

### Basic usage

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

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

### Without GT instance

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

### Currency and number formatting

```typescript
// German locale formatting
const germanPrice = formatMessage('Preis: {price, number, currency}', {
  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%"
```

### Template library

```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!" (in French)
console.log(templates.itemCount(5)); // "5 éléments"
```

---

## Notes

- Requires explicit locale specification in options
- Supports same ICU message format features as GT class method
- Returns empty string for empty input templates
- Variables are processed before ICU formatting rules

## Next steps

- Check out [`Intl.MessageFormat` documentation](https://formatjs.github.io/docs/intl-messageformat/) for more options
- Use GT class [`formatMessage`](/docs/core/class/methods/formatting/format-message) for stateful formatting
- Format numbers with standalone [`formatNum`](/docs/core/functions/formatting/format-num)
- Learn about `FormatVariables` type