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 FCL 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};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    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(())
}

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 a machine-managed integrity lock plus optional AI provenance (model and confidence), with by-hand edits detected automatically.
• Use API Overview when you want catalog QA for release readiness: missing translations, stale messages, ICU checks, semantic metadata conflicts, and obsolete entries.
• 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.

ferrocat-cli GitHub releases also include a prebuilt x86_64-unknown-linux-musl archive named ferrocat-<version>-x86_64-unknown-linux-musl.tar.gz. Use that artifact when a hosted or containerized Linux environment needs a musl-friendly ferrocat binary without compiling from crates.io.

Compatibility policy

• MSRV: Rust 1.93.0
• MSRV policy: align with OXC when practical, while avoiding churn from tracking only the newest stable toolchain
• MSRV bumps: raising the MSRV is treated as a minor-version change and called out in the changelog; patch releases should not raise the MSRV.
• Prebuilt CLI target: x86_64-unknown-linux-musl is validated in CI and published as a smoke-tested GitHub Release archive for ferrocat-cli.
• Semver: the public API follows semantic versioning; breaking changes ship in a new major version
• Docs surface: README examples, rustdoc, and the site should stay aligned

Site-specific development

For the documentation site itself:

cd docs
pnpm install
pnpm dev
pnpm build