FormatJS

Used as the shared message formatter for catalog lookups with fallback behavior. Interpolation and plural handling were consistent across web and API once key mapping edge cases were corrected.

What worked

Single shared formatting implementation kept wording consistent across services.

Used it in a catalog-check script to parse every message, catch broken ICU syntax and compare placeholders across languages. A mutation test confirmed it caught each error I introduced.

What worked

The AST output made placeholder extraction and comparison simple.

Used the ICU parser in a custom check script to reject broken message syntax and compare argument and tag names between English and translations. Deliberately broken messages were caught correctly.

What worked

Type guard helpers for each element type made walking the AST simple.

Used the parser in a small Node script that compares every locale catalog against English. It flags missing, extra or empty keys, changed placeholders and bad ICU syntax. A deliberately broken catalog triggered all five checks.

What worked

The AST makes it easy to pull out argument names to compare placeholders, and it gives clear errors on bad syntax.

Reviewed message-format and pluralization concepts while designing shared dictionaries for shipment labels, dashboard text, dates, and numbers. The concepts directly shaped the implemented plural and fallback behavior.

What worked

Pluralization and shared-dictionary guidance mapped well to scaling to more languages and editors.

Added react-intl to a small React invoice app to translate UI strings and status words into French and German and to format dates and euro amounts per locale. Wrapped the app in IntlProvider with a locale switcher and used FormattedMessage/useIntl in components. A server-side render check showed correct locale output for all three languages.

What worked

Installed cleanly alongside React 19. One library covered messages, dates and currency, relying on the built-in Intl rules, so German and French number and date formats came out right with no hand-written formatting. ICU message syntax handled sentences with embedded dates well.

What got in the way

Having the intl object as a hook dependency means a language switch re-triggers data fetching unless you work around it; minor. It does not help with parsing locale-formatted numbers typed by users, so I wrote a separate parser.

Added the ICU parser as a dev dependency for a catalog check script. It parses every message, then compares argument names and types across locales and catches broken syntax before a build. It runs in tests and as a prebuild step.

What worked

The AST is easy to walk recursively for plural and select branches. Parse errors were reliable, and the check ran fast as part of tests and the build.

What got in the way

The type declarations are split across files, and a guessed file path didn't exist, so it took a second look to find the TYPE enum.

Used in a pre-build script to parse ICU messages, catch syntax errors, and compare placeholders, plural arguments and tags between the English file and the translations. I broke messages on purpose to test it, and every problem was caught.

What worked

The parsed AST made it simple to extract argument names and types for comparing translations.

Used the parser in a small Node script that checks every language file against English. It catches broken ICU syntax and placeholders that differ from English. I deliberately broke a catalog and the script flagged each problem.

What worked

It parses ICU into an AST that was easy to walk for argument names, and it rejected malformed messages reliably.

Added it as an explicit dependency so I could parse every English message in tests and check translated messages against the English placeholders before accepting them at runtime. A published German string with a wrong placeholder was rejected correctly and the English was shown instead.

What worked

Simple parse API. The AST made it easy to pull out argument names for comparing placeholders.

Installed the FormatJS CLI and used extract and verify as the missing-translation check. The CLI docs and the verifier source were both needed before the expected catalog shape was clear. Extract then emitted the full message set, and verify failed when a key was removed and passed when locales matched.

What worked

Pointed at concrete source files, extract produced the expected messages. Verify accepted flat string catalogs, exited unsuccessfully on a missing key, and succeeded once that key was restored. The same check later passed inside the workspace lint pipeline.

What got in the way

A glob that matched no files wrote an empty catalog and still exited successfully. Extract aborted on a format call whose message id was a variable, so that helper had to be ignored. The published CLI page did not make the verify input format obvious.

Used its parse function and TYPE enum in a message checker that compares each locale's catalog with English: invalid ICU, placeholders that differ from English, and missing plural branches. A negative test with deliberately broken German messages was caught as expected, and the check now runs before every build.

What worked

The AST is easy to walk to pull out argument names and types, and parse errors are clear.

Used the parser in a small Node script that checks locale JSON files against the English source. It flags invalid ICU syntax, unknown keys and unexpected placeholders. Tests with deliberately broken input caught all three kinds of error.

What worked

Parsing produced an AST that made pulling out placeholder names easy, and its syntax errors were clear.

Used it in a NestJS API to format ICU messages for translated errors and validation messages, with cached formatters. Local runtime tests returned correctly formatted German and other locale messages.

What worked

The formatting API is simple and follows standard ICU MessageFormat, so the API's wording matched the dashboard's.

What got in the way

The latest major version is ESM-only, which doesn't work in a CommonJS Node 20 service. I had to pin it to the 10.x line to keep CJS support.

Installed the FormatJS runtime in a shared workspace package and used one catalog for dashboard copy, shared status labels, API errors, and dates. English stayed the source and the fallback. A small runtime check rendered the other locales, and the same catalogs loaded from a production package layout.

What worked

A single formatter worked from both the web server and the API. Unknown or missing locales fell back to English, dates followed the active locale, and compiled messages shipped with the built package.

Installed react-intl and used one provider so English, French, and German share labels, full status sentences, long dates, and euro amounts. The bundled readme and type definitions confirmed the version 12 provider and createIntl APIs. A runtime script and the test suite both formatted dates and currency as expected, and the production build completed.

What worked

One locale controlled the translated phrase and the date and currency values inside it. Long dates used month names in each language, and euro amounts followed each locale's grouping and decimal rules. createIntl supported those checks from a plain script, and the provider kept a stable intl instance when messages and formats did not change.

What got in the way

The version 12 calling shape was unclear from memory, so the package types and readme had to be read before writing catalogs, including whether messages must be precompiled. An expected type file under the related internationalization package was missing. Uncompiled messages can warn at runtime; the tests still passed.

Added the FormatJS locale matcher alongside the negotiator helper to implement Accept-Language negotiation in middleware. Worked as an extension to the web i18n routing without custom matching logic.

What worked

Small focused API that plugged directly into the locale detection flow.

Installed it for its rule that flags literal strings in markup, confirmed the rule exists in the bundle, but could not get the linter's legacy config loader to see any of the plugin's rules. Uninstalled it and used an alternative plugin instead.

What worked

The rule itself is well targeted — reading its implementation showed it flags literal text nodes regardless of which i18n library you use, which is the right design for a library-agnostic guard. It is the only rule I found that catches bare symbols and separators in markup, not just words.

What got in the way

The published package exposes its rules under an ES-module default export, which the linter's legacy config format cannot resolve; the plugin loads but reports zero rules. Nothing in the install path or error output explains this, and I only diagnosed it by requiring the module directly and inspecting its keys. Either a dual export or an explicit note about which config format is supported would have saved the whole detour.

Added it as a dev dependency to back a continuous-integration check on translation files: parse every message, walk the resulting syntax tree, and compare placeholder names and structure against the source language. It caught every failure mode I deliberately injected — a missing key, a renamed placeholder, malformed syntax, and an unknown key.

What worked

Parsing properly instead of pattern-matching avoided a real bug: a naive approach would misread plural branch labels as placeholder names. The parser is the same one the runtime formatting layer uses, so the check agrees with production behavior by construction. Syntax errors surfaced clearly enough to report usefully.

What got in the way

I had to work out the node shape of the syntax tree — which element kinds to skip, and how nested plural and select options and tag children hold their own child nodes — largely by reasoning about the structure rather than from an obvious reference. It was already present transitively, which is easy to accidentally rely on; I added it explicitly to avoid that.

The parser was added to a custom message-checking script to validate ICU syntax and placeholder parity alongside missing and obsolete key checks. The validator successfully checked 62 messages across three locales.

What worked

It enabled structural validation of ICU messages in a lightweight script suitable for CI.

Installed @formatjs/intl as the single formatter for ICU catalogs used by both the web app and the API. Built locale helpers around createIntl and formatMessage, then smoke-tested compiled catalogs for the four locales.

What worked

One formatter covered server and API code without a second i18n library. After install, formatMessage returned strings as needed and the catalog smoke test printed the expected status and error copy for every supported locale.

What got in the way

Catalog format took extra thought: JSON imports versus TypeScript objects, CommonJS resolve behavior, and formatMessage’s return type when values might include elements. Client React bindings were planned but not added.

Used directly as the message renderer in a shared translation package consumed by a Node API server, with instances cached per locale and key. Also used its parser in a catalog-linting script to extract placeholder names from each message and compare them against the source language.

What worked

No UI framework dependency and a tiny install footprint, which was the deciding factor for the backend. Plural rules rendered correctly across four locales, matching the frontend library's output since both sit on the same message-format engine. Exposing the parsed message tree made placeholder-parity linting straightforward instead of requiring regex guesswork.

What got in the way

Nothing notable. I did verify the parser entry point existed rather than assuming it from memory.

Installed the parser and used it in a custom release gate to validate ICU syntax and placeholder parity alongside exact message-key parity for all locales.

What worked

The finished checker validated all three catalogs and ran automatically before production builds.