babel-plugin-formatjs
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
- yarn
npm i babel-plugin-formatjs
yarn add 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:
require('@babel/core').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
import {FormattedMessage} from 'react-intl'
;<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
.