@postinumero/formatjs-tools

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

CLI

extract

Extract from app to lang/.extracted.json:

formatjs-tools extract

--path (multiple)

Extract from src to lang/.extracted.json:

formatjs-tools extract --path src

--out-file

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

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

aggregate

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

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

formatjs-tools aggregate

collect

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

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

formatjs-tools collect

merge

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

Merge:

• .lang/aggregated/[environment:]<locale>.json
• .lang/collected/[environment:]<locale>.json

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

formatjs-tools merge

compile

Compile merged files for each environment and locale.

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

formatjs-tools compile

To customize the output directory and enable hashed filenames:

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:]<locale> to hash values

config

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

formatjs-tools config

process-messages

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

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:

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.

Filename Convention

Files must follow the format:

lang/[environment:]<locale>.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).

config.json

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:

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

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

{
  "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:

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

2. Add prebuild script

   package.json:

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