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 message format patterns.

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

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

Prop

Type

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

FormatVariables Type

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

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

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

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

Pluralization with ICU Format

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

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/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 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 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 message format patterns.

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

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

Prop

Type

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

FormatVariables Type

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

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

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

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

Pluralization with ICU Format

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

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/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 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 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 message format patterns.

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

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"

Property	Type	Optional	Description
`locales`	`string \| string[]`	✓	Locale(s) to use 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 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

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

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

Pluralization with ICU Format

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

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/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 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 for more options
Format numbers with formatNum

formatMessage

On this page

formatMessage

On this page

formatMessage

On this page