Process string messages for translation from modules that use react-intl, specifically:

  • Parse and verify that messages are ICU-compliant w/o any syntax issues.
  • Remove description from message descriptor to save bytes since it isn't used at runtime.
  • Option to remove defaultMessage from message descriptor to save bytes since it isn't used at runtime.
  • Automatically inject message ID based on specific pattern.

Installation

npm i babel-plugin-formatjs

Usage

This Babel plugin only visits ES6 modules which import React Intl.

The default message descriptors for the app's default language will be processed from: defineMessages(), defineMessage(), intl.formatMessage and <FormattedMessage>; all of which are named exports of the React Intl package.

Via babel.config.json (Recommended)

babel.config.json

{
  "plugins": [
    [
      "formatjs",
      {
        "idInterpolationPattern": "[sha512:contenthash:base64:6]",
        "ast": true
      }
    ]
  ]
}

Via Node API

The extract message descriptors are available via the metadata property on the object returned from Babel's transform() API:

transform('code', {
  plugins: ['formatjs'],
}) // => { code, map, ast, metadata['formatjs'].messages, metadata['formatjs'].meta };

Options

overrideIdFn

A function with the signature (id: string, defaultMessage: string, description: string|object) => string which allows you to override the ID both in the extracted javascript and messages.

idInterpolationPattern

If certain message descriptors don't have id, this pattern will be used to automaticallygenerate IDs for them. Default to [sha512:contenthash:base64:6]. See nodejs crypto createHash for hash algorithms & nodejs buffer docs for digest encodings.

removeDefaultMessage

Remove defaultMessage field in generated js after extraction.

additionalComponentNames

Additional component names to extract messages from, e.g: ['FormattedFooBarMessage']. NOTE: By default we check for the fact that FormattedMessage are imported from moduleSourceName to make sure variable alias works. This option does not do that so it's less safe.

additionalFunctionNames

Additional function names to extract messages from, e.g: ['$formatMessage']. Use this if you prefer to alias formatMessage to something shorter like $t.

pragma

parse specific additional custom pragma. This allows you to tag certain file with metadata such as project. For example with this file:

// @intl-meta project:my-custom-project
<FormattedMessage defaultMessage="foo" id="bar" />

and with option {pragma: "@intl-meta"}, we'll parse out // @intl-meta project:my-custom-project into {project: 'my-custom-project'} in the result file.

ast

Pre-parse defaultMessage into AST for faster runtime perf. This flag doesn't do anything when removeDefaultMessage is true.

preserveWhitespace

When set to true, message trimming is disabled.

flatten

Whether to hoist selectors & flatten sentences as much as possible. For example:

I have {count, plural, one{a dog} other{many dogs}}

becomes

{count, plural, one{I have a dog} other{I have many dogs}}

The goal is to provide as many full sentences as possible since fragmented sentences are not translator-friendly. This transformation is applied before ID generation when using overrideIdFn or idInterpolationPattern, ensuring the ID is based on the flattened message format.