@postinumero/formatjs-tools

An implementation of FormatJS Application Workflow, declaring package messages with a convention.

CLI

$3

Extract from app to lang/.extracted.json:

``sh
formatjs-tools extract
`

#### --path (multiple)

Extract from src to lang/.extracted.json:

`sh
formatjs-tools extract --path src
`

#### --out-file

Extract from app to lang/en-DEFAULT.json:

`sh
formatjs-tools extract --out-file lang/en-DEFAULT.json
`

$3

Aggregate the extracted files from dependencies into a single file for each environment and locale.

Aggregate messages to .lang/aggregated/[environment:].json:

`sh
formatjs-tools aggregate
`

$3

Collect the translation files into a single file for each environment and locale.

Collect messages to .lang/collected/[environment:].json:

`sh
formatjs-tools collect
`

$3

Merge aggregated messages and collected translations for each environment and locale.

Merge:

- .lang/aggregated/[environment:].json
- .lang/collected/[environment:].json

(saved to: .lang/merged/[environment:].json)

`sh
formatjs-tools merge
`

$3

Compile merged files for each environment and locale.

By default, output is written to .lang/compiled/[environment:].json:

`sh
formatjs-tools compile
`

To customize the output directory and enable hashed filenames:

`sh
formatjs-tools compile --out-dir public/.compiled-lang --hash
`

- --out-dir sets a custom output path
- --hash appends a content hash to filenames (e.g. en-US-abc123.json)
- A manifest.json is also generated to map [environment:] to hash values

$3

Write internal locale and environment configuration to .lang/config.json.

`sh
formatjs-tools config
`

$3

Run all of the commands above in correct order:
config, extract, aggregate, collect, merge, compile

`sh
formatjs-tools process-messages
`

You can give options to individual commands by prefixing the option name with the command name (e.g. --extract.path src).

API

Use programmatically in Node.js:

`ts
import {
aggregate,
collect,
compile,
config,
extract,
merge,
processMessages,
} from "@postinumero/formatjs-tools/commands";

await aggregate();
`

Config

Configuration is based on:

- Filenames in the lang directory
- Optional config.json in the project root
- Environment variables (locales, environments)

See the example app for reference.

$3

Files must follow the format:

`
lang/[environment:].json
`

- environment is optional and may include multiple segments (e.g. com.example.test).
By convention, use reverse domain naming. Environments inherit from their parent and subdomains — e.g. com.example.test inherits from com.example, com, example.test and test.
- locale can include a region (e.g. en-US). Regional locales inherit from the base (e.g. en-US inherits from en).

When messages are extracted, they are saved as .extracted.json.
These files are autogenerated and should not be edited manually — feel free to add them to .gitignore.

To override default messages for all locales, you can create a .default.json file (optionally per environment).

$3

Use config.json to customize environments and locales.
By default, all locales and environments are inferred from filenames in the lang directory.

You can override or extend this behavior:

Replace detected values entirely:

`json
{
"locales": ["en", "fi"],
"environments": ["development", "production"]
}
`

Or extend/modify what's found in the lang directory:


`json
{
"locales": {
"include": ["fr"], // Adds "fr" to any locales found in lang/
"exclude": ["fi"] // Removes "fi" if found
},
"environments": {
"include": ["test"] // Adds "test" environment
}
}
`

Library Usage

Example lib uses @formatjs/ts-transformer and ts-patch.

1. Extend your TSConfig\\

tsconfig.json:

`json
{
"extends": "@postinumero/formatjs-tools/configs/tsconfig.lib.json"
}
`

2. Add prebuild script

package.json:

`json
{
"scripts": {
"prebuild": "formatjs-tools extract --path src",
"build": "tspc"
}
}
``