# Ferrocat

> Performance-first translation catalogs for Gettext, ICU MessageFormat, and JSON-friendly runtime workflows.

## Docs

- [Architecture](https://ferrocat.dev/architecture): Architectural context for Ferrocat, including decision records and engineering notes.
- [ADR Index](https://ferrocat.dev/architecture/adr): Index of accepted architecture decision records for Ferrocat.
- [ADR 0001: Rust-Native, Performance-First Core](https://ferrocat.dev/architecture/adr/0001-rust-native-performance-first-core): Accepted architecture decision record: rust native performance first core.
- [ADR 0002: Provide Both Owned and Borrowed Parse APIs](https://ferrocat.dev/architecture/adr/0002-owned-and-borrowed-parse-apis): Accepted architecture decision record: owned and borrowed parse apis.
- [ADR 0003: Use Byte-Oriented Scanning and Separate Structure From Semantics](https://ferrocat.dev/architecture/adr/0003-byte-oriented-scanning-and-structural-separation): Accepted architecture decision record: byte oriented scanning and structural separation.
- [ADR 0004: Model `msgstr` by Semantics Instead of Always Using `Vec<String>`](https://ferrocat.dev/architecture/adr/0004-model-msgstr-by-semantics): Accepted architecture decision record: model msgstr by semantics.
- [ADR 0005: Treat ICU as the Canonical Model and Gettext as a Compatibility Bridge](https://ferrocat.dev/architecture/adr/0005-icu-canonical-model-and-gettext-bridge): Accepted architecture decision record: icu canonical model and gettext bridge.
- [ADR 0006: Separate the PO Core from the High-Level Catalog API](https://ferrocat.dev/architecture/adr/0006-separate-po-core-from-high-level-catalog-api): Accepted architecture decision record: separate po core from high level catalog api.
- [ADR 0007: Do Not Support `previous_msgid` History](https://ferrocat.dev/architecture/adr/0007-drop-previous-msgid-history): Accepted architecture decision record: drop previous msgid history.
- [ADR 0008: Normalize Headerless PO Files on Write](https://ferrocat.dev/architecture/adr/0008-normalize-headerless-po-output): Accepted architecture decision record: normalize headerless po output.
- [ADR 0009: Use Versioned, Truncated SHA-256 Keys for Runtime Catalog Compilation](https://ferrocat.dev/architecture/adr/0009-runtime-catalog-compiled-key-strategy): Accepted architecture decision record: runtime catalog compiled key strategy.
- [ADR 0010: Add a Locale-Resolved Compiled Catalog Artifact API](https://ferrocat.dev/architecture/adr/0010-compiled-catalog-artifact-api): Accepted architecture decision record: compiled catalog artifact api.
- [ADR 0011: Add an NDJSON Storage Format for High-Level Catalog Workflows](https://ferrocat.dev/architecture/adr/0011-ndjson-catalog-storage-format): Accepted architecture decision record: ndjson catalog storage format.
- [ADR 0012: Make the High-Level Catalog API ICU-Native by Default and Move Gettext Plurals Behind an Explicit Compat Mode](https://ferrocat.dev/architecture/adr/0012-icu-native-core-and-gettext-compat-semantics): Accepted architecture decision record: icu native core and gettext compat semantics.
- [ADR 0013: Add a Rust-Native Catalog Combine API](https://ferrocat.dev/architecture/adr/0013-rust-native-catalog-combine-api): Accepted architecture decision record: rust native catalog combine api.
- [ADR 0014: Keep Ferrocat Host-Neutral and Let Palamedes Own JS/TS Application Integration](https://ferrocat.dev/architecture/adr/0014-ferrocat-palamedes-boundary): Accepted architecture decision record: ferrocat palamedes boundary.
- [ADR 0015: Add ICU Authoring Diagnostics Without Owning Runtime Formatting](https://ferrocat.dev/architecture/adr/0015-icu-authoring-diagnostics): Accepted architecture decision record: icu authoring diagnostics.
- [ADR 0016: Add Progressive Semantic Message Metadata Around `msgid`](https://ferrocat.dev/architecture/adr/0016-semantic-message-metadata): Accepted architecture decision record: semantic message metadata.
- [ADR 0017: Add Catalog Audit Reports Without Reintroducing Fuzzy Matching](https://ferrocat.dev/architecture/adr/0017-catalog-audit-reports): Accepted architecture decision record: catalog audit reports.
- [ADR 0018: Add Machine-Translation Metadata to Catalog Entries](https://ferrocat.dev/architecture/adr/0018-machine-translation-entry-metadata): Accepted architecture decision record: machine-translation entry metadata.
- [ADR 0019: Version the Compiled Artifact JSON Contract](https://ferrocat.dev/architecture/adr/0019-versioned-artifact-json-contract): Accepted architecture decision record: versioned compiled artifact JSON contract.
- [ADR 0020: Keep the 1.x Catalog Layer in ferrocat-po Behind Feature Profiles](https://ferrocat.dev/architecture/adr/0020-catalog-layer-packaging-boundary): Accepted architecture decision record: keep the 1.x catalog layer in ferrocat-po behind feature profiles.
- [ADR 0021: Drop Source Line Numbers from the Catalog Layer](https://ferrocat.dev/architecture/adr/0021-drop-source-line-numbers): Accepted architecture decision record: catalog references track the source file only, not a line number.
- [ADR 0022: Machine-Managed Value Integrity and AI Provenance](https://ferrocat.dev/architecture/adr/0022-machine-managed-value-integrity-and-ai-provenance): Accepted architecture decision record: a top-level integrity lock for machine-managed values plus a compact, engine-agnostic AI provenance field, superseding the structured machine-translation metadata.
- [ADR 0023: Drop gettext Flags and Merge Comments](https://ferrocat.dev/architecture/adr/0023-drop-gettext-flags-merge-comments): Accepted architecture decision record: the catalog model drops the gettext flag concept (fuzzy and *-format) and collapses the two comment kinds into one notes field, while keeping obsolete entries.
- [ADR 0024: Stable Origin Scope Anchor](https://ferrocat.dev/architecture/adr/0024-origin-scope-anchor): Accepted architecture decision record: catalog origins gain an optional stable scope (enclosing component or function), serialized as a file#scope anchor in both PO and FCL.
- [ADR 0025: Obsolete Age and Age-Based Cleanup](https://ferrocat.dev/architecture/adr/0025-obsolete-age-and-cleanup): Accepted architecture decision record: obsolete becomes a presence-plus-payload field carrying an optional write-once since date, with a caller-provided clock and an age-based drop strategy, so hosts can garbage-collect long-unused entries without making Ferrocat time-dependent.
- [ADR 0026: Use CLDR Root Catalog Order by Default](https://ferrocat.dev/architecture/adr/0026-cldr-root-catalog-order): Accepted architecture decision record: Ferrocat orders catalog identities with the CLDR root order used by Intl.Collator(en-US), backed by a compact generated table instead of ICU4X.
- [ADR 0027: Preserve Translator Comments and Flags as Opaque Round-Trip State](https://ferrocat.dev/architecture/adr/0027-opaque-po-metadata-roundtrip): Accepted architecture decision record: the catalog layer keeps translator comments and per-entry flags attached to the message identity through update and combine without giving them any semantic meaning.
- [ADR 0028: Project Fuzzy as Opt-In Review State](https://ferrocat.dev/architecture/adr/0028-fuzzy-review-state-projection): Accepted architecture decision record: coverage, audit, and review classify fuzzy entries without exposing arbitrary gettext flags or slowing the default catalog projection.
- [ADR 0029: Add Explicit PO/FCL Catalog Conversion](https://ferrocat.dev/architecture/adr/0029-explicit-po-fcl-conversion): Accepted architecture decision record: cross-format conversion uses separate source and target modes, the canonical message model, and atomic file replacement.
- [ADR 0030: Make Catalog File Write Durability Explicit](https://ferrocat.dev/architecture/adr/0030-catalog-file-write-durability): Accepted architecture decision record: update_catalog_file keeps fully synced writes by default and offers atomic rename without sync barriers for regenerable artifacts.
- [README Theme Composition](https://ferrocat.dev/architecture/adr/readme-theme-composition): Native README ownership and nested Sebastian and Ferramenta themes.
- [Archive](https://ferrocat.dev/archive): Archived planning and historical documentation retained for project context.
- [Migration Inventory](https://ferrocat.dev/archive/migration-inventory): Archived route map for the completed README and docs-orig migration.
- [Archived Plans](https://ferrocat.dev/archive/plans): Historical planning documents that remain useful as project context but are not current roadmap commitments.
- [ferrocat Porting Plan for `pofile-ts`](https://ferrocat.dev/archive/plans/2026-03-14-ferrocat-porting-plan): Archived implementation plan for the original pofile-ts porting effort.
- [Guide](https://ferrocat.dev/guide): Product-level orientation for Ferrocat, from installation to catalog modes and runtime workflows.
- [Catalog Modes](https://ferrocat.dev/guide/catalog-modes): Mental model for Ferrocat's three supported combinations of storage format and message semantics.
- [Community](https://ferrocat.dev/guide/community): Contribution, governance, and release-operation links for Ferrocat contributors and evaluators.
- [Getting Started](https://ferrocat.dev/guide/getting-started): Install Ferrocat, run the first parse/stringify workflow, and choose the next docs path.
- [Palamedes Ecosystem](https://ferrocat.dev/guide/palamedes): How Ferrocat and Palamedes fit together across catalog infrastructure, extraction, framework adapters, and runtime delivery.
- [Project Status](https://ferrocat.dev/guide/project-status): Current strengths, roadmap themes, compatibility policy, and long-term direction for Ferrocat.
- [Runtime Compilation](https://ferrocat.dev/guide/runtime-compilation): Overview of Ferrocat's runtime-facing compile layers for normalized catalogs and locale-resolved artifacts.
- [Releases And Upgrading](https://ferrocat.dev/guide/upgrading): Where Ferrocat changelogs live and how to upgrade between stable releases safely.
- [Notes](https://ferrocat.dev/notes): Engineering notes that capture exploratory or forward-looking technical context for Ferrocat.
- [Scan Architecture Notes](https://ferrocat.dev/notes/2026-03-14-scan-architecture): Engineering note on the scan module and byte-oriented parser structure.
- [Bundler-Aware Message Sidecars](https://ferrocat.dev/notes/2026-03-17-bundler-aware-message-sidecars): Future-facing note about bundler-aware message sidecars and runtime distribution.
- [Operations](https://ferrocat.dev/operations): Operational documentation for releases and repository-level maintenance.
- [Release Verification](https://ferrocat.dev/operations/release-verification): Checklist for validating a published Ferrocat release after automation completes.
- [Performance](https://ferrocat.dev/performance): Benchmark methodology, fixtures, and measurement history for Ferrocat.
- [Benchmark Fixtures](https://ferrocat.dev/performance/benchmark-fixtures): Reference guide to the generated and static benchmark fixture sets used in ferrocat-bench.
- [External Benchmarking](https://ferrocat.dev/performance/benchmarking): Methodology and operating rules for serious external benchmark comparisons.
- [Quality](https://ferrocat.dev/quality): Evidence for correctness and maintainability, including conformance coverage and test coverage policy.
- [Conformance](https://ferrocat.dev/quality/conformance): Conformance snapshot, methodology, and current upstream-derived coverage for Ferrocat.
- [Test Coverage](https://ferrocat.dev/quality/test-coverage): Coverage goals, local commands, CI thresholds, and artifact locations for Ferrocat.
- [Reference](https://ferrocat.dev/reference): Durable technical reference material for Ferrocat's public API and core behaviors.
- [API Overview](https://ferrocat.dev/reference/api-overview): Guide to Ferrocat's public API layers and when to use each entry point.
- [Gettext Task Landscape](https://ferrocat.dev/reference/gettext-task-landscape): A workflow-level map of gettext-inspired catalog jobs, ecosystem patterns, and Ferrocat's product direction.

## More

- [Full documentation](https://ferrocat.dev/llms-full.txt): Complete documentation as one Markdown file.