defineMessages

The defineMessages function allows you to define messages in your code that can be easily extracted using the @formatjs/cli.

ICU MessageFormat syntax

Messages use the ICU MessageFormat syntax. ICU MessageFormat is a syntax for defining localised text messages that can handle variable substitution, plurals, and other complex use cases. If you're not familiar with ICU MessageFormat syntax, you can find more information on the FormatJS documentation page.

Usage

Defining a single message

You can define a single message with defineMessage function. It accepts a descriptor object that describes the message, and returns it back. This function is used to make the message descriptor statically analysable and extractable.

const myMessage = defineMessage({
  id: 'unique-message-id',
  defaultMessage: 'Message content',
})

Defining multiple messages

To define multiple messages, you can use defineMessages, which accepts an object where each property is set to an object containing a message descriptor. Just like defineMessage, it returns the input back as is.

const messages = defineMessages({
  example: {
    id: 'example',
    defaultMessage: 'This is an example',
  },
})

Property names of the object do not matter, as they don't affect the extraction in any way.

Message Descriptors

Message descriptors are objects that describe a message and its properties. The following properties can be defined for a message:

• id: A unique identifier for the message.
• defaultMessage: The default message to display if no translation is available.
• description (optional): A description of the message for translators.

Common pitfalls

No dynamic descriptors

Message descriptors should be statically analysable, otherwise the extractor will not be able to extract them. This means that you should not use dynamic values in the message descriptor objects.

function createID(key) {
  return `prefix.${key}`
}

const PREFIX = `our-prefix`

const unexportedMessages = defineMessages({
  greeting: {
    id: createID('greeting'),
    defaultMessage: 'Hello!',
  },
  farewell: {
    id: `${PREFIX}.farewell`,
    defaultMessage: 'Goodbye!',
  },
})

In this example, neither of the defined messages are statically analysable:

• greeting calls the createID function to create an ID
• farewell uses the PREFIX variable in a template string

You should instead use static values for the ID and defaultMessage properties.

const messages = defineMessages({
  greeting: {
    id: 'prefix.greeting',
    defaultMessage: 'Hello!',
  },
  farewell: {
    id: 'our-prefix.farewell',
    defaultMessage: 'Goodbye!',
  },
})

New lines in template strings

Template strings in JavaScript can be broken into multiple lines. Unfortunately, the extractor currently does not handle this case, removing new lines from the string. If you need new lines, you should use the \n character or custom tags that will wrap the contents into <p>, <div> elements.