Skip to content
Ferrocat

Catalog Modes

Mental model for Ferrocat's three supported combinations of storage format and message semantics.

Catalog Modes

Ferrocat is one catalog engine with a few explicit ways to store and interpret messages. You can start with the format that fits your team today and still keep a path toward richer messages, cleaner diffs, AI translation metadata, release audits, and runtime artifacts.

The two choices Ferrocat keeps visible are simple:

  • Storage: where catalog records live and how they are reviewed.
  • Message behavior: whether a message is plain text, classic plural data, or a richer message with placeholders, formatting, plurals, selects, and tags.

Keeping those choices explicit makes migrations safer, runtime compilation clearer, and translator-tool interoperability easier to reason about.

The three supported modes

ModeStorage formatMessage modelUse when you want to...
Classic Gettext catalog modeGettext POGettext-compatible pluralsstay close to existing PO catalogs and traditional plural workflows
ICU-native Gettext PO modeGettext POICU MessageFormatkeep translator-facing PO files, comments, and tooling, but author richer messages with placeholders, plural/select logic, and formatting
ICU-native NDJSON catalog modeNDJSON catalog storageICU MessageFormatstore catalogs as one-message-per-line JSON records that are easier to diff, merge, stream, batch, and hand to external services

There is intentionally no NDJSON + Gettext-compatible plurals mode. Gettext-compatible plural behavior belongs to PO-shaped catalogs, while NDJSON is the native storage path for ICU-style catalog records.

Why NDJSON matters for larger teams

PO is the right compatibility format when you need translator tools that already understand source strings, translations, comments, references, flags, and plural entries. NDJSON solves a different collaboration problem: every message is its own line-delimited JSON record.

That shape makes catalog changes easier to review in pull requests and easier to merge when several people or automated jobs touch the same locale. Unrelated message edits do not land inside one large PO block, conflicts are usually narrower, and the repository does not have to depend on a custom Git merge driver being available in every hosted review or web-merge path.

Use NDJSON when your catalog workflow is more application- and pipeline-centered than PO-tooling-centered, especially for large teams, generated updates, or external systems that already work naturally with JSON records.

Both PO and NDJSON can carry machine-translation metadata for AI-assisted workflows. Ferrocat keeps the storage compact, verifies the translation hash when writing, and drops stale metadata once the translated text has been edited.

That application-centered path is where Palamedes becomes important: Palamedes can own extraction, framework adapters, and runtime packaging while Ferrocat owns the catalog semantics underneath.

Why the split matters

  • Gettext PO and NDJSON are storage decisions.
  • Gettext-compatible plurals and ICU MessageFormat are semantics decisions.
  • Explicit combinations make migrations, validation, and runtime compilation easier to review in code.
  • The NDJSON storage choice is also a collaboration choice: it trades some PO-specific fidelity for cleaner line-level diffs and simpler merge conflict handling.