Getting Started

Use Ferrocat when translations need to behave like product data. A catalog should be easy to update, review, validate, audit, track through AI-assisted translation, and compile for runtime delivery. The umbrella ferrocat crate is the recommended entry point for application code.

You do not need to know every translation-system term before starting. Ferrocat can work with translator-friendly PO files, richer ICU-style messages, reviewable NDJSON records, and machine-translation metadata, but the first workflow is simple: parse a catalog, change it deliberately, write it back, and build from there.

Install the crate

cargo add ferrocat

The public workspace crates line up by responsibility:

• ferrocat: umbrella crate and default dependency
• ferrocat-po: PO parsing, serialization, merge/combine helpers, and high-level catalog update APIs
• ferrocat-icu: ICU MessageFormat parsing, structural helpers, and authoring diagnostics

Quick start

use ferrocat::{SerializeOptions, parse_po, stringify_po};

let mut file = parse_po(
    r#"
msgid "hello"
msgstr "world"
"#,
)?;

file.items[0].msgstr = "Welt".to_owned().into();

let rendered = stringify_po(&file, &SerializeOptions::default());
assert!(rendered.contains(r#"msgstr "Welt""#));
# Ok::<(), Box<dyn std::error::Error>>(())

Where to go next

• Read Catalog Modes when you want to understand the storage choices behind translator-friendly files, rich messages, and line-oriented catalog records.
• Read Runtime Compilation when your application should load compiled catalog artifacts instead of raw translator files.
• Use API Overview when AI-generated translations need model, confidence, modification, and hash metadata that is cleaned up after human edits.
• Use API Overview when you want catalog QA for release readiness: missing translations, stale messages, ICU checks, semantic metadata conflicts, obsolete entries, and visible fuzzy flags.
• Use API Overview when you want richer-message analysis or source/translation compatibility diagnostics.
• Read Ferrocat And Palamedes when you want the app-framework view: extraction, macros, runtime adapters, and how Palamedes uses Ferrocat as its catalog layer.
• Open API Overview when you need to choose between low-level PO parsing, high-level catalog workflows, and ICU helpers.
• Open Gettext Task Landscape when you already know established Gettext-style jobs and want to map them to Ferrocat APIs.

Compatibility policy

• MSRV: Rust 1.88
• MSRV policy: support a Rust stable release roughly 9-12 months behind current stable when practical, rather than only the newest stable toolchain
• Semver: the public API is treated seriously, but the project is still pre-1.0
• Docs surface: README examples, rustdoc, and the site should stay aligned

Site-specific development

For the documentation site itself:

pnpm install
pnpm dev
pnpm build