# React-intl-exporter CLI

This library adapts `@formatjs/cli` tool to export translations in a smart way.

React-intl-exporter CLI extracts all messages from the application and saves them for all specified languages. If a file already exists, the tool merges its content with currently extracted messages.
Every message is an object with at least two fields:

- `defaultMessage` - same like generated by the original tool; contains value of `defaultMessage` found in the application;
- `translatedMessage` - it's a message `defaultMessage` translated to the current language; when generated for first time, it has the same value as `defaultMessage`; it should be translated manually; compilation process should take this values into account, not from `defaultMessage` fields.

If there is a new message not available in the JSON file, it will be added. If a message from JSON is not extracted, it will be removed from the file.
If in JSON file is already a message with the same key but different `defaultMessage` than in generated, generated message will replace the existing one. If both key and `defaultMessage` are the same, message is not changed.

**NOTE** All commands here assumes that you use `yarn` tool. Using `npm` or any other tool doesn't change much. Please adapt an exact command to the tool you use.

## Installation

You can add this tool to your application in these steps:

1. Install the package:

```shell
yarn add react-intl-extractor-cli -D
```

2. Add a new script to `scripts` section in your `packages.json` file, e.g.

```
"intl:extract": "intl_extractor extract "src/**/!(*.test).js" --languages en,de,pl",
```

3. Create a file with formatter defined by the tool (to support `translatedMessage` instead of `defaultMessage`). Minimal file `formatter.js` is:

```js
const defaultFormatter = require('react-intl-extractor-cli').defaultFormatter;
module.exports.default = defaultFormatter;
```

4. When you use compiler from `@formatjs/cli`, specify `--format <formatter_file>` parameter where `<formatter_file` is a location of `formatter.js` file created in a previous step. Name of the file can be any, however in both steps must be the same.

## Simple usage

You can add extraction and compilation commands to `scripts` section of `package.json` file:

```json
"intl:extract": "intl_extractor extract \"src/**/!(*.test).js\" src/messages --languages en,pl",
"intl:compile": "formatjs compile-folder src/messages src/translations --format src/utils/compileFormatter.js",
```

Then you can use just:
`yarn intl:extract` - to extract or update already extracted messages
`yarn intl:compile` - to compile extracted (and manually translated) message files to files consumable by `react-intl`.

# Commands

## Extract

`yarn intl_extractor extract [options] <inputFile> <outputFolder>`

Most of the parameters used in this command are the same as for original `formatjs extract` command. You can check them [here](https://formatjs.io/docs/tooling/cli/).
Below are described differences.

`<inputFile>` is a pattern to determine in which files messages are located. Eg. `"src/**/!(*.test).js"`.

`<outputFolder>` determines where output files with extracted messages should be located. It's also a location where currently existing message files are tried to be found.

### Parameters

`--languages <codes>` It's the most important parameter as it specifies language codes for which translation messages should be generated. `<codes>` contain code strings separated by comma "," signs.

`--verbose` Using this parameter you inform the tool that you expect more details about processed languages and messages.

## Help

`intl_extractor help`
It just displays help message
