GitHub

Overview

The formatMessage method formats messages with variable substitution and locale‑aware formatting. Built on top of Format.JS's intl-messageformat library, it supports ICU MessageFormat patterns.

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

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

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

Reference

Parameters

Prop

Type

Options Object

Property	Type	Optional	Description
`locales`	`string \| string[]`	✓	Locale(s) used for formatting (overrides instance defaults)
`variables`	`FormatVariables`	✓	Object containing variables for message interpolation

FormatVariables Type

type FormatVariables = {
  [key: string]: string | number | Date | boolean;
};

Returns

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

Behaviour

Variable Substitution

Simple variables: {variableName} → replaced with a 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 behaviour 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}
Pluralisation: {count, plural, =0 {none} =1 {one} other {many}}
Selection: {gender, select, male {he} female {she} other {they}}
Select ordinal: {place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}

Examples

Basic Variable Substitution

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

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

Pluralisation with ICU Format

const message = gt.formatMessage(
  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your basket',
  {
    variables: { count: 3 }
  }
);
console.log(message); // "You have 3 items in your basket"

Number and Currency Formatting

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

const orderStatusMessage = gt.formatMessage(`
  Order #{orderId} status update:
  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
  - Total: {total, number, ::currency/GBP}
  - Status: {status, select, 
      pending {Pending} 
      shipped {Dispatched} 
      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 MessageFormat syntax for advanced formatting using 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 the Intl.MessageFormat documentation for more options
Format numbers with formatNum

Overview

The formatMessage method formats messages with variable substitution and locale‑aware formatting. Built on top of Format.JS's intl-messageformat library, it supports ICU MessageFormat patterns.

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

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

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

Reference

Parameters

Prop

Type

Options Object

Property	Type	Optional	Description
`locales`	`string \| string[]`	✓	Locale(s) used for formatting (overrides instance defaults)
`variables`	`FormatVariables`	✓	Object containing variables for message interpolation

FormatVariables Type

type FormatVariables = {
  [key: string]: string | number | Date | boolean;
};

Returns

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

Behaviour

Variable Substitution

Simple variables: {variableName} → replaced with a 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 behaviour 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}
Pluralisation: {count, plural, =0 {none} =1 {one} other {many}}
Selection: {gender, select, male {he} female {she} other {they}}
Select ordinal: {place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}

Examples

Basic Variable Substitution

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

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

Pluralisation with ICU Format

const message = gt.formatMessage(
  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your basket',
  {
    variables: { count: 3 }
  }
);
console.log(message); // "You have 3 items in your basket"

Number and Currency Formatting

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

const orderStatusMessage = gt.formatMessage(`
  Order #{orderId} status update:
  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
  - Total: {total, number, ::currency/GBP}
  - Status: {status, select, 
      pending {Pending} 
      shipped {Dispatched} 
      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 MessageFormat syntax for advanced formatting using 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 the Intl.MessageFormat documentation for more options
Format numbers with formatNum

Overview

The formatMessage method formats messages with variable substitution and locale‑aware formatting. Built on top of Format.JS's intl-messageformat library, it supports ICU MessageFormat patterns.

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

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

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

Property	Type	Optional	Description
`locales`	`string \| string[]`	✓	Locale(s) used for formatting (overrides instance defaults)
`variables`	`FormatVariables`	✓	Object containing variables for message interpolation

FormatVariables Type

type FormatVariables = {
  [key: string]: string | number | Date | boolean;
};

Simple variables: {variableName} → replaced with a 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 behaviour 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}
Pluralisation: {count, plural, =0 {none} =1 {one} other {many}}
Selection: {gender, select, male {he} female {she} other {they}}
Select ordinal: {place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}

Examples

Basic Variable Substitution

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

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

Pluralisation with ICU Format

const message = gt.formatMessage(
  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your basket',
  {
    variables: { count: 3 }
  }
);
console.log(message); // "You have 3 items in your basket"

Number and Currency Formatting

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

const orderStatusMessage = gt.formatMessage(`
  Order #{orderId} status update:
  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
  - Total: {total, number, ::currency/GBP}
  - Status: {status, select, 
      pending {Pending} 
      shipped {Dispatched} 
      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 MessageFormat syntax for advanced formatting using 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 the Intl.MessageFormat documentation for more options
Format numbers with formatNum

formatMessage

On this page

formatMessage

On this page

formatMessage

On this page

GitHubStar on GitHub

GitHubStar on GitHub

Star on GitHub

Star on GitHub