| 1 | # babel-plugin-react-intl
|
| 2 |
|
| 3 | Extracts string messages for translation from modules that use [React Intl][].
|
| 4 |
|
| 5 | ## Dependencies
|
| 6 |
|
| 7 | ### React Intl
|
| 8 |
|
| 9 | This Babel plugin works with React Intl v2.x
|
| 10 |
|
| 11 | ### Babel
|
| 12 |
|
| 13 | - **3.x** of this plugin works with Babel 7
|
| 14 | - **2.x** works with Babel 6
|
| 15 | - **1.x** works with Babel 5
|
| 16 |
|
| 17 | ## Installation
|
| 18 |
|
| 19 | ```sh
|
| 20 | $ npm install babel-plugin-react-intl
|
| 21 | ```
|
| 22 |
|
| 23 | ## Usage
|
| 24 |
|
| 25 | **This Babel plugin only visits ES6 modules which `import` React Intl.**
|
| 26 |
|
| 27 | The default message descriptors for the app's default language will be extracted from: `defineMessages()`, `<FormattedMessage>`, and `<FormattedHTMLMessage>`; all of which are named exports of the React Intl package.
|
| 28 |
|
| 29 | If a message descriptor has a `description`, it'll be removed from the source after it's extracted to save bytes since it isn't used at runtime.
|
| 30 |
|
| 31 | ### Via `.babelrc` (Recommended)
|
| 32 |
|
| 33 | **.babelrc**
|
| 34 |
|
| 35 | ```json
|
| 36 | {
|
| 37 | "plugins": [
|
| 38 | [
|
| 39 | "react-intl",
|
| 40 | {
|
| 41 | "messagesDir": "./build/messages/"
|
| 42 | }
|
| 43 | ]
|
| 44 | ]
|
| 45 | }
|
| 46 | ```
|
| 47 |
|
| 48 | #### Options
|
| 49 |
|
| 50 | - **`messagesDir`**: The target location where the plugin will output a `.json` file corresponding to each component from which React Intl messages were extracted. If not provided, the extracted message descriptors will only be accessible via Babel's API.
|
| 51 |
|
| 52 | - **`enforceDescriptions`**: Whether message declarations _must_ contain a `description` to provide context to translators. Defaults to: `false`.
|
| 53 |
|
| 54 | - **`enforceDefaultMessage`**: Whether message declarations _must_ contain a `defaultMessage` to fallback when translations are not present. Defaults to: `true`.
|
| 55 |
|
| 56 | - **`extractSourceLocation`**: Whether the metadata about the location of the message in the source file should be extracted. If `true`, then `file`, `start`, and `end` fields will exist for each extracted message descriptors. Defaults to `false`.
|
| 57 |
|
| 58 | - **`moduleSourceName`**: The ES6 module source name of the React Intl package. Defaults to: `"react-intl"`, but can be changed to another name/path to React Intl.
|
| 59 |
|
| 60 | - **`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.
|
| 61 |
|
| 62 | - **`removeDefaultMessage`**: Remove `defaultMessage` field in generated js after extraction.
|
| 63 |
|
| 64 | - **`additionalComponentNames`**: Additional component names to extract messages from, e.g: `['FormattedFooBarMessage']`. **NOTE**: By default we check for the fact that `FormattedMessage` & `FormattedHTMLMessage` are imported from `moduleSourceName` to make sure variable alias works. This option does not do that so it's less safe.
|
| 65 |
|
| 66 | - **`extractFromFormatMessageCall`**: Opt-in to extract from `intl.formatMessage` call with the same restrictions, e.g: has to be called with object literal such as `intl.formatMessage({ id: 'foo', defaultMessage: 'bar', description: 'baz'})`
|
| 67 |
|
| 68 | ### Via Node API
|
| 69 |
|
| 70 | The extract message descriptors are available via the `metadata` property on the object returned from Babel's `transform()` API:
|
| 71 |
|
| 72 | ```javascript
|
| 73 | require('@babel/core').transform('code', {
|
| 74 | plugins: ['react-intl']
|
| 75 | }); // => { code, map, ast, metadata['react-intl'].messages };
|
| 76 | ```
|
| 77 |
|
| 78 | [react intl]: http://formatjs.io/react/
|