ferrocat-po 2.2.0

Performance-first PO parsing, serialization, and catalog update primitives for ferrocat.
Documentation

ferrocat-po

Performance-first catalog parsing, serialization, merge helpers, release audits, and runtime compilation for ferrocat.

This crate contains the PO core plus the feature-gated catalog workflow layer. Use it when translation files need to be parsed, serialized, updated, reviewed, checked for release readiness, or compiled into application-facing payloads.

Add it with:

cargo add ferrocat-po

This crate covers both the low-level PO surface and the higher-level catalog layer. For PO-only dependency profiles, disable default features.

Feature flags

ferrocat-po enables full by default. full currently means catalog, so the default build exposes the complete current PO and catalog API surface.

  • catalog: high-level catalog parse, update, combine, audit, metadata, FCL, plural, and runtime compile APIs, plus their hashing, tempfile, serde JSON, ICU, and CLDR plural-data dependencies
  • serde: serde support for low-level PO document types; catalog also enables it for catalog-layer JSON/report shapes
  • compile, mt, and plurals: reserved subsystem aliases that currently imply catalog; they do not reduce or split the catalog API surface yet

Use default-features = false for the low-level PO parser, borrowed parser, serializer, string helpers, and lightweight merge_catalog helper without catalog-layer dependencies. Enabling compile, mt, or plurals currently has the same dependency effect as enabling catalog.

At the catalog layer, it supports three explicit modes:

  • classic Gettext catalog mode: Gettext PO + gettext-compatible plurals
  • ICU-native Gettext PO mode: Gettext PO + ICU MessageFormat
  • ICU-native FCL catalog mode: FCL (Ferrocat Catalog Lines) storage + ICU MessageFormat

FCL + gettext-compatible plurals is intentionally unsupported.

See the repository's FCL format specification for the line format and escaping rules behind ICU-native FCL storage.

Use this crate when you want that surface directly:

  • parse_po / parse_po_borrowed for raw PO parsing
  • stringify_po for PO serialization
  • merge_catalog for lightweight catalog merges
  • parse_catalog, update_catalog, and NormalizedParsedCatalog::compile for higher-level catalog workflows across Gettext PO and FCL storage
  • MachineMetadata (integrity lock plus optional AiProvenance) and machine_translation_hash for marking machine-managed values in PO or FCL and detecting later by-hand edits
  • audit_catalogs for read-only release QA across source and target catalogs
  • compile_catalog_artifact for requested-locale runtime artifacts with fallback resolution and missing reports
  • compile_catalog_artifact_selected for selected compiled-ID subsets of those runtime artifacts

audit_catalogs answers whether a catalog set is ready to ship without rewriting anything. The default report checks completeness, target-only stale messages, ICU syntax, ICU source/translation compatibility, semantic metadata conflicts, and obsolete entries.

parse_po_borrowed keeps many fields as references into the input buffer and accepts the same LF, CRLF, and bare CR line-ending forms as the owned parse_po parser.

If you want the umbrella dependency instead, use ferrocat.