Crate ferrocat_po

Expand description

Performance-first PO parsing and serialization.

The crate exposes both owned and borrowed parsers for gettext PO files, a byte-oriented UTF-8 parser entry point, plus helpers for serialization and higher-level catalog update workflows.

§Feature flags

The default feature set is full, which currently enables the catalog workflow layer.

catalog exposes high-level catalog parsing, updates, combining, audits, machine-translation metadata, plural handling, FCL storage, and runtime artifact compilation. It also enables the catalog-layer dependencies used for hashing, atomic file updates, serde JSON output, ICU diagnostics, and CLDR plural data.
serde enables serde implementations for low-level PO document types and is also enabled by catalog for catalog-layer JSON/report shapes.
compile, mt, and plurals are reserved subsystem aliases. Today they imply catalog; they do not reduce or split the catalog API surface.

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.

§Examples

use ferrocat_po::{PoFile, SerializeOptions, parse_po, stringify_po};

let input = "msgid \"Hello\"\nmsgstr \"Hallo\"\n";
let file = parse_po(input)?;
assert_eq!(file.items[0].msgid, "Hello");

let output = stringify_po(&file, &SerializeOptions::default());
assert!(output.contains("msgid \"Hello\""));

use ferrocat_po::parse_po_bytes;

let input = b"msgid \"Hello\"\nmsgstr \"Hallo\"\n";
let file = parse_po_bytes(input)?;
assert_eq!(file.items[0].msgstr[0], "Hallo");

use ferrocat_po::{
    CompileCatalogArtifactOptions, CompileSelectedCatalogArtifactOptions,
    CompiledCatalogIdIndex, ParseCatalogOptions, compile_catalog_artifact_selected,
    parse_catalog,
};

let source = parse_catalog(
    ParseCatalogOptions::new("msgid \"Hello\"\nmsgstr \"Hello\"\n", "en").with_locale("en"),
)?
.into_normalized_view()?;
let requested = parse_catalog(
    ParseCatalogOptions::new("msgid \"Hello\"\nmsgstr \"Hallo\"\n", "en").with_locale("de"),
)?
.into_normalized_view()?;
let index = CompiledCatalogIdIndex::new(&[&requested, &source], ferrocat_po::CompiledKeyStrategy::FerrocatV1)?;
let compiled_ids = index.iter().map(|(id, _)| id).collect::<Vec<_>>();
let compiled = compile_catalog_artifact_selected(
    &[&requested, &source],
    &index,
    &CompileSelectedCatalogArtifactOptions::new("de", "en", &compiled_ids),
)?;

assert_eq!(compiled.messages.len(), 1);

use ferrocat_po::{CatalogAuditOptions, ParseCatalogOptions, audit_catalogs, parse_catalog};

let source = parse_catalog(
    ParseCatalogOptions::new("msgid \"Hello {name}\"\nmsgstr \"Hello {name}\"\n", "en")
        .with_locale("en"),
)?
.into_normalized_view()?;
let target = parse_catalog(
    ParseCatalogOptions::new("msgid \"Hello {name}\"\nmsgstr \"Hallo\"\n", "en")
        .with_locale("de"),
)?
.into_normalized_view()?;
let report = audit_catalogs(&[&source, &target], &CatalogAuditOptions::new("en"))?;

assert!(report.has_errors());

Modules§

diagnostic_codes: Stable machine-readable diagnostic codes emitted by ferrocat-po.

Structs§

AiProvenancecatalog: AI provenance for a machine-managed value.
BorrowedHeader: Borrowed header entry from the PO header block.
BorrowedPoFile: Borrowed PO document that reuses slices from the original input whenever possible.
BorrowedPoItem: Borrowed gettext message entry.
CatalogAuditCheckscatalog: Enables or disables individual catalog audit checks.
CatalogAuditDiagnosticcatalog: One machine-readable catalog audit diagnostic.
CatalogAuditIcuOptionscatalog: ICU-specific options used by catalog audit checks.
CatalogAuditMessageRefcatalog: Catalog message reference attached to audit diagnostics.
CatalogAuditOptionscatalog: Options controlling catalog audit checks.
CatalogAuditReportcatalog: Report returned by audit_catalogs.
CatalogAuditSummarycatalog: Summary counters for a catalog audit report.
CatalogCombineInputcatalog: One catalog input passed to super::combine_catalogs.
CatalogCombineResultcatalog: Result returned by catalog combine operations.
CatalogCombineStatscatalog: Basic counters describing a catalog combine operation.
CatalogCoverageMessagecatalog: One classified message row in a coverage report.
CatalogCoverageOptionscatalog: Options controlling catalog coverage reports.
CatalogCoverageReportcatalog: Structured catalog coverage report.
CatalogFileCombineResultcatalog: Result returned by catalog file combine operations.
CatalogLocaleCoveragecatalog: Coverage counters for one target locale.
CatalogLocaleReviewcatalog: Review details for one target locale.
CatalogMachineTranslationMessagecatalog: One machine-translation metadata classification.
CatalogMachineTranslationReviewcatalog: Machine-translation metadata summary for one locale.
CatalogMessagecatalog: Public message representation returned by super::parse_catalog.
CatalogMessageKeycatalog: Stable lookup key for catalog messages.
CatalogOrigincatalog: Source origin metadata for an extracted message.
CatalogReviewOptionscatalog: Options controlling catalog review reports.
CatalogReviewReportcatalog: Read-only catalog review report comparing two normalized catalog states.
CatalogReviewSummarycatalog: Aggregate counters for a catalog review report.
CatalogSourceChangecatalog: One source identity change.
CatalogSourceChangeReportcatalog: Source identity add/remove summary.
CatalogStatscatalog: Basic counters describing an update operation.
CatalogTranslationChangecatalog: One target translation change.
CatalogTranslationChangeReportcatalog: Translation change summary for one locale.
CatalogUpdateResultcatalog: Result returned by catalog update operations.
CombineCatalogFilesOptionscatalog: Options for combining catalog files on disk.
CombineCatalogOptionscatalog: Options for combining multiple catalogs into one deterministic catalog.
CompileCatalogArtifactIcuOptionscatalog: ICU-specific options used while compiling catalog artifacts.
CompileCatalogArtifactOptionscatalog: Options controlling high-level compiled catalog artifact generation.
CompileCatalogArtifactReportOptionscatalog: Options controlling compiled artifact generation with a sibling provenance report.
CompileCatalogOptionscatalog: Options controlling runtime catalog compilation.
CompileSelectedCatalogArtifactOptionscatalog: Options controlling selected-subset compiled catalog artifact generation.
CompiledCatalogcatalog: Runtime-oriented lookup structure compiled from a normalized catalog.
CompiledCatalogArtifactcatalog: Host-neutral compiled runtime artifact for one requested locale.
CompiledCatalogArtifactReportcatalog: Result returned by super::compile_catalog_artifact_report.
CompiledCatalogDiagnosticcatalog: Diagnostic emitted by super::compile_catalog_artifact.
CompiledCatalogIdDescriptioncatalog: Metadata describing one compiled runtime ID for a specific catalog set.
CompiledCatalogIdIndexcatalog: Stable compiled runtime ID index built from one or more normalized catalogs.
CompiledCatalogMissingMessagecatalog: Missing-message record emitted by super::compile_catalog_artifact.
CompiledCatalogProvenanceReportcatalog: Provenance metadata for one compiled requested-locale artifact.
CompiledCatalogPseudolocalizationOptionscatalog: Options controlling compiled catalog artifact pseudolocalization.
CompiledCatalogResolutioncatalog: Provenance row for one compiled runtime message identity.
CompiledCatalogUnavailableIdcatalog: Known compiled runtime ID that was not present in the provided catalog set.
CompiledMessagecatalog: A compiled runtime message keyed by a derived lookup key.
DescribeCompiledIdsReportcatalog: Report returned by CompiledCatalogIdIndex::describe_compiled_ids.
Diagnosticcatalog: Non-fatal issue collected while parsing or updating catalogs.
DiagnosticCode: Stable machine-readable diagnostic code.
ExtractedPluralMessagecatalog: Structured plural message input used by catalog update operations.
ExtractedSingularMessagecatalog: Structured singular message input used by catalog update operations.
Header: A single header entry from the PO header block.
IcuPseudolocalizationOptionscatalog: Options controlling ICU-aware pseudolocalization.
MachineMetadatacatalog: Metadata for a catalog value that was set or managed by a machine.
MergeMessageInput: Borrowed message input for the lightweight PO merge helper.
MsgStrIter: Iterator over MsgStr values.
NormalizedParsedCatalogcatalog: Parsed catalog with fast key-based lookup helpers.
ObsoleteInfocatalog: Obsolete-entry payload. Presence on CatalogMessage::obsolete marks the entry obsolete; since records when it became obsolete so hosts can age-cleanup with ObsoleteStrategy::DropObsoleteBefore.
ParseCatalogOptionscatalog: Options for parsing a catalog into the higher-level message model.
ParseError: Error returned when parsing or unescaping PO content fails.
ParsePosition: One-based line/column context plus the byte offset for a parse error.
ParsedCatalogcatalog: Parsed catalog plus diagnostics and normalized headers.
PluralSourcecatalog: Source-side plural forms for structured catalog messages.
PoFile: An owned PO document.
PoItem: A single gettext message entry.
PoVec: Inline-capable vector for the small per-item collections (references, flags, comments, metadata) that hold a single element in the overwhelmingly common case, avoiding a heap allocation for the backing buffer.
PoVecIntoIter: Owning iterator returned by PoVec::into_iter.
RenderOptionscatalog: Shared rendering options for catalog serialization.
SerializeOptions: Options controlling PO serialization.
SourceExtractedMessagecatalog: Source-first extractor input that lets ferrocat infer plural structure.
UpdateCatalogFileOptionscatalog: Options for updating a catalog file on disk.
UpdateCatalogOptionscatalog: Options for in-memory catalog updates.

Enums§

ApiErrorcatalog: Error returned by catalog parsing and update APIs.
BorrowedMsgStr: Borrowed translation payload for a PO item.
CatalogCombineSelectioncatalog: Selection rule used after definitions from all inputs have been counted.
CatalogConflictStrategycatalog: Strategy used when multiple catalogs define conflicting translations for one identity.
CatalogFileFormatcatalog: File format used by disk-based catalog combine operations.
CatalogMachineTranslationStatuscatalog: Machine-translation metadata freshness status.
CatalogMessageStatuscatalog: Canonical catalog message status used by coverage and review reports.
CatalogModecatalog: Valid high-level catalog mode combinations.
CatalogReviewTranslationcatalog: Owned translation value used in review reports.
CatalogSemanticscatalog: High-level semantics used by the catalog API.
CatalogSourceChangeKindcatalog: Kind of source identity change.
CatalogStorageFormatcatalog: Storage format used by the high-level catalog API.
CatalogUpdateInputcatalog: Input payload accepted by catalog update operations.
CompileCatalogArtifactReportSelectioncatalog: Message selection for super::compile_catalog_artifact_report.
CompiledCatalogResolutionKindcatalog: How one compiled runtime message resolved for a requested-locale artifact.
CompiledCatalogTranslationKindcatalog: High-level translation kind associated with a compiled runtime ID.
CompiledKeyStrategycatalog: Built-in key strategy used when compiling runtime catalogs.
CompiledTranslationcatalog: Translation value stored in a compiled runtime catalog.
DiagnosticSeveritycatalog: Severity level attached to a Diagnostic.
EffectiveTranslationcatalog: Owned translation value materialized from a parsed catalog.
EffectiveTranslationRefcatalog: Borrowed view over a message translation.
ExtractedMessagecatalog: Structured extractor input accepted by super::update_catalog and super::update_catalog_file.
IcuSyntaxPolicycatalog: ICU parser behavior used by catalog audit and runtime artifact validation.
MsgStr: Message translation payload for a PO item.
ObsoleteStrategycatalog: Strategy used for messages that disappear from the extracted input.
OrderBycatalog: Sort order used when writing output catalogs.
PlaceholderCommentModecatalog: Controls whether placeholder hints are emitted as extracted comments.
PluralEncodingcatalog: Encoding used for plural messages in PO files.
TranslationShapecatalog: Public translation shape returned from parsed catalogs.

Constants§

COMPILED_CATALOG_ARTIFACT_SCHEMA_VERSIONcatalog: JSON schema version emitted by CompiledCatalogArtifact serialization.

Functions§

audit_catalogscatalog: Audits a normalized catalog set for catalog QA and authoring issues.
combine_catalog_filescatalog: Combines catalog files and atomically replaces the requested output path.
combine_catalogscatalog: Combines multiple catalogs into one deterministic catalog.
compile_catalog_artifactcatalog: Compiles one requested-locale runtime artifact from one or more normalized catalogs.
compile_catalog_artifact_reportcatalog: Compiles one requested-locale runtime artifact with a sibling provenance report.
compile_catalog_artifact_selectedcatalog: Compiles one requested-locale runtime artifact for a selected subset of compiled IDs.
compiled_keycatalog: Derives the default stable runtime lookup key for msgid and msgctxt.
escape_string: Escapes a PO string literal payload.
extract_quoted: Extracts and unescapes the first quoted PO string from line.
extract_quoted_cow: Extracts and unescapes the first quoted PO string from line, borrowing from the input when no escapes are present.
machine_translation_hashcatalog: Computes the integrity-lock hash for a translation value.
measure_catalog_coveragecatalog: Builds a read-only completeness and coverage report for normalized catalogs.
merge_catalog: Merges extracted messages into an existing PO catalog while preserving the existing translation payload.
parse_catalogcatalog: Parses catalog content into the higher-level representation used by ferrocat’s catalog APIs.
parse_po: Parses PO content into the owned PoFile representation.
parse_po_borrowed: Parses PO content into a borrowed representation.
parse_po_bytes: Parses UTF-8 PO bytes into the owned PoFile representation.
pseudolocalize_compiled_catalog_artifactcatalog: Pseudolocalizes the final runtime messages in a compiled catalog artifact.
review_catalogscatalog: Compares previous and current normalized catalog states for translator review.
stringify_po: Serializes a PoFile back into gettext PO text.
unescape_string: Unescapes a PO string literal payload.
update_catalogcatalog: Merges extracted messages into an existing catalog and returns updated catalog content.
update_catalog_filecatalog: Updates a catalog on disk and only writes the file when the rendered output changes.

Type Aliases§

IcuFormatterSupportPolicycatalog: Callback used to validate runtime support for ICU formatters.