Skip to content
Ferrocat
v3.6.0Ferramenta

Ferrocat 3.6, a translation catalog engine for Rust

Your translations, ready to ship.Catalogs that Git can merge and people can trust.

Every sentence an application shows lives in a translation catalog. Ferrocat keeps those catalogs right as the code changes: it updates them, checks what translators wrote, keeps human corrections visible and compiles what your application loads. It reads Gettext PO, ICU messages and FCL, a format with one line per message. For teams whose translations live in the repository.

Start with Rustcargo add ferrocatAudit your catalogscargo install ferrocat-cli
  • 457 of 457conformance checks from polib, pofile, Babel, ICU and FormatJS
  • 3 modesGettext PO, ICU PO and FCL, chosen explicitly
  • 1 lineper message in FCL, so unrelated edits merge cleanly
  • Rust 1.94+MIT or Apache-2.0, library and CLI

Every sentence your app says, in one catalog.

An application speaks in hundreds of small sentences: a button label, a greeting, a line that counts the items in a cart. To show them in German or Japanese, a team collects every sentence from the code into a translation catalog. Translators fill in the other side, and the application looks each sentence up while it runs. The catalog lives next to the code, in the same repository, and changes with it.

The most common catalog is the PO file of GNU gettext. Each entry holds the sentence in the source language, its translation, the place in the code it came from and a note for the translator. Ferrocat reads and writes PO, so the tools your translators use today keep working.

The hard part is not reading the file. It is keeping it right while the code moves on. Developers add sentences, reword others and delete a few. Every change has to reach every language without losing a translation someone already paid for. Ferrocat compares what the code says now with what the catalog holds, adds what is new, keeps what still matches, and sets aside what the code no longer uses, with the date it happened.

What the code says nowSourceExtractedMessage
  • Hello {name}from src/Header.tsx#Greeting
  • Pay nowcontext “checkout”, from src/Checkout.tsx#PayButton
  • {count, plural, one {# item} other {# items}} in your cartfrom src/Cart.tsx#CartSummary
The German catalog, updatedupdate_catalog()
  1. msgid ""
  2. msgstr ""
  3. "Content-Transfer-Encoding: 8bit\n"
  4. "Content-Type: text/plain; charset=utf-8\n"
  5. "Language: de\n"
  6. "MIME-Version: 1.0\n"
  7. "X-Generator: ferrocat\n"
  9. #: src/Cart.tsx#CartSummary
  10. msgid "{count, plural, one {# item} other {# items}} in your cart"
  11. msgstr ""
  13. #~ #@ obsolete-since: 2026-11-07
  14. #~ #: src/Cart.tsx#CartSummary
  15. #~ msgid "Continue shopping"
  16. #~ msgstr "Weiter einkaufen"
  18. #. Shown after sign-in
  19. #: src/Header.tsx#Greeting
  20. msgid "Hello {name}"
  21. msgstr "Hallo {name}"
  23. #. Primary checkout button
  24. #: src/Checkout.tsx#PayButton
  25. msgctxt "checkout"
  26. msgid "Pay now"
  27. msgstr "Jetzt bezahlen"

Real output of ferrocat 3.4.2: one message added with an empty translation, two messages kept with their translation, and one message the code no longer uses marked obsolete, with the date.

Translator-friendly files. Git-friendly lines.

Keep PO where translation tools expect it. Choose FCL where machines write the catalog and Git has to merge it.

A PO entry spans several lines: comments, a context, the source, the translation. When two branches both touch a catalog, Git compares those lines, and edits that have nothing to do with each other can still meet in one conflict. Ferrocat Catalog Lines, FCL for short, writes each message on exactly one line and sorts the lines in a fixed order. Unrelated edits land on different lines, and an entry can never be torn apart by a merge.

You choose the format per catalog, and say so explicitly. Classic PO keeps gettext’s own plural rules. ICU PO and FCL carry ICU messages. Converting between ICU PO and FCL keeps every message, with its origin and its notes. Switch the sheet below to see the same German catalog both ways.

The German catalog, 3 messagesde.fcl, convert_catalog()
  1. %FCL1(tab)source=en(tab)locale=de(tab)order=collated
  2. {count, plural, one {# item} other {# items}} in your cart(tab)(tab){count, plural, one {# Artikel} other {# Artikel}} im Warenkorb(tab)r=src/Cart.tsx#CartSummary
  3. Hello {name}(tab)(tab)Hallo {name}(tab)r=src/Header.tsx#Greeting(tab)c=Shown after sign-in
  4. Pay now(tab)checkout(tab)Jetzt bezahlen(tab)r=src/Checkout.tsx#PayButton(tab)c=Primary checkout button

Real output of ferrocat 3.4.2. In FCL each message is one line, and marks a tab between its fields: message, context, translation, then where it comes from (r=) and the note for translators (c=).

How to choose a catalog mode

Plurals and placeholders, checked.

A translation can read perfectly and still break the screen. Ferrocat compares its structure with the source before your users see it.

“1 items in your cart” is the classic mistake. ICU messages avoid it: a message names its placeholders in braces and lists one wording per plural form, and the application picks the right one at run time. The source below says “1 item” and “3 items” correctly, and the German translation has to keep that structure.

Translators are careful people, and placeholders still get translated, dropped or flattened. The runtime then shows a raw brace, an empty gap or the wrong plural. Ferrocat parses both messages and compares them: every placeholder the source needs, every plural and choice, every formatting style and markup tag.

The messageparse_icu()

English source

{count, plural, one {# item} other {# items}} in your cart

German translation

{count, plural, one {# Artikel} other {# Artikel}} im Warenkorb

What Ferrocat reportscompare_icu_messages()

No diagnostics. The translation keeps the source’s structure.

Real output of ferrocat 3.4.2. Choose a translation above.

Find the missing words before your users do.

Point the command-line tool at your catalogs. It reports every gap, and its exit status fails the build.

A release audit compares every target language with the source catalog: translations that are missing or empty, entries still marked for review, ICU messages that do not parse or do not match their source. Errors and warnings come with the language, the message and a stable code, in plain text for people and as JSON for your tooling.

Put it in the pipeline that builds your release. A missing translation then stops the merge, not a customer.

The German catalogmissing.po
  1. msgid ""
  2. msgstr ""
  3. "Language: de\n"
  4. "Content-Type: text/plain; charset=UTF-8\n"
  6. msgctxt "checkout"
  7. msgid "Pay now"
  8. msgstr ""
  10. msgctxt "greeting"
  11. msgid "Hello {name}"
  12. msgstr "Hallo {name}"
The command-line resultexit 1

ferrocat audit --source-locale en --source docs/examples/source.po --target de=docs/examples/missing.po

  • Catalog audit: 2 source messages, 1 target locales, 1 diagnostics (1 errors, 0 warnings, 0 info)
  • error catalog.empty_translation [de "checkout" / "Pay now"; de]: Locale `de` has an empty translation.

Exit status 1: the release check fails.

Saved runs of the Rust command-line tool against an English source with the same two messages.

Show the English source and the JSON report
The English sourcesource.po
  1. msgid ""
  2. msgstr ""
  3. "Language: en\n"
  4. "Content-Type: text/plain; charset=UTF-8\n"
  6. msgctxt "checkout"
  7. msgid "Pay now"
  8. msgstr "Pay now"
  10. msgctxt "greeting"
  11. msgid "Hello {name}"
  12. msgstr "Hello {name}"
The same result as JSON--format json
  1. {
  2. "diagnostics": [
  3. {
  4. "code": "catalog.empty_translation",
  5. "message": "Locale `de` has an empty translation.",
  6. "name": "de",
  7. "severity": "error",
  8. "source_key": {
  9. "locale": "de",
  10. "msgctxt": "checkout",
  11. "msgid": "Pay now"
  12. }
  13. }
  14. ],
  15. "summary": {
  16. "diagnostics": 1,
  17. "errors": 1,
  18. "infos": 0,
  19. "source_messages": 2,
  20. "target_locales": 1,
  21. "warnings": 0
  22. }
  23. }

Audit checks and report formats

A human correction leaves a trace.

Machine translation can write the first draft. When a person improves it, the catalog knows.

Many teams let a model translate new strings and ask a person to review the result. The trouble starts on the next run: which values did the machine write, and which did a reviewer fix? Overwrite the wrong one, and a careful correction is gone.

When a tool writes a translation, Ferrocat can store a fingerprint of exactly that value beside it, with the model and its confidence. As long as the text and the fingerprint agree, the value is still machine output. Once a person edits it, they no longer agree, and every later review or translation run can see that a human stepped in. Ferrocat reports it; your policy decides what happens next.

Written by machine translationde.fcl
  1. %FCL1(tab)source=en(tab)locale=de(tab)order=collated
  2. Pay now(tab)checkout(tab)Jetzt bezahlen(tab)r=src/Checkout.tsx#PayButton(tab)c=Primary checkout button(tab)lock=MJvtg6ldT1tuIn1smwSDEg(tab)ai=example/mt:0.92
After a reviewer’s correctionde.fcl
  1. %FCL1(tab)source=en(tab)locale=de(tab)order=collated
  2. Pay now(tab)checkout(tab)Zahlungspflichtig bestellen(tab)r=src/Checkout.tsx#PayButton(tab)c=Primary checkout button(tab)lock=MJvtg6ldT1tuIn1smwSDEg(tab)ai=example/mt:0.92
  • Translations changed since the last state1
  • Machine translations still as written0
  • Machine translations a person has changed1

Real output of ferrocat 3.4.2, review_catalogs() comparing the two states. The fingerprint (lock=) still belongs to “Jetzt bezahlen”, so the new value is reported as a person’s change, not as machine output.

Fingerprints and machine-translation metadata

Compile what the application loads.

One file per language, keyed for fast lookup, with every fallback written down.

An application does not need comments, origins or review marks while it runs. It needs the right text for a key, quickly. Ferrocat compiles the catalogs for one language into exactly that: a map from stable keys to messages, ready to ship as JSON beside your code.

Gaps do not disappear in the process. A message without a translation falls back to the next language you name, and the artifact lists it under missing, so the build can warn or stop.

The German catalogde.po
  1. msgid "Hello {name}"
  2. msgstr "Hallo {name}"
  4. msgctxt "checkout"
  5. msgid "Pay now"
  6. msgstr "Jetzt bezahlen"
What the application loadscompile_catalog_artifact()
  1. {
  2. "diagnostics": [],
  3. "messages": {
  4. "JM4sleTdWBE": "Jetzt bezahlen",
  5. "NfZ_uPJfKww": "{count, plural, one {# item} other {# items}} in your cart",
  6. "ndf4SYIwaQI": "Hallo {name}"
  7. },
  8. "missing": [
  9. {
  10. "key": "NfZ_uPJfKww",
  11. "requested_locale": "de",
  12. "resolved_locale": "en",
  13. "source_key": {
  14. "msgctxt": null,
  15. "msgid": "{count, plural, one {# item} other {# items}} in your cart"
  16. }
  17. }
  18. ],
  19. "schema_version": 1
  20. }

Real output of ferrocat 3.4.2, with English as the fallback. The cart message has no German translation yet, so it falls back to the English source and is listed under missing.

Runtime artifacts and fallback chains

Catalog work at the speed of your build.

Reading a catalog and adding new strings to it, Ferrocat finished ahead of GNU msgmerge and the gettext libraries we compared for Node.js, PHP and Python.

Catalog work runs more often than people expect: on every extraction, in every pull request that touches a string, before every release, once per language. On a large product, that is many thousands of messages each time. When the catalog step takes seconds, developers start skipping it.

Ferrocat scans the bytes of a catalog directly, and its update moves messages from the old catalog into the new one instead of copying them. Switch the chart between the two everyday jobs.

Time for the same work

Ferrocat = 1×, the line through every row. A bar past it took longer.

The published comparisons also cover pofile, pofile-ts and Babel, and a full update with ICU checks. Every task and its conditions

Show the figures as a table
TaskToolVersion measuredTime
Read a cataloggettext-parsergettext-parser@9.1.122.09×
Read a cataloggettext/gettextgettext/gettext@5.7.310.00×
Read a catalogpolibpolib@1.2.022.28×
Add new stringsGNU msgmergemsgmerge (GNU gettext-tools) 1.060.55×
Add new stringspolibpolib@1.2.034.58×
Add new stringsgettext/gettextgettext/gettext@5.7.316.73×

Held to the tests of the tools teams know.

PO has quirks that only show up in real catalogs. Ferrocat runs cases taken from the libraries that met them first.

A catalog engine is only as good as its odd cases: escaped quotes, a byte-order mark, obsolete entries, contexts, values spread over several lines. The libraries below have collected such cases for years. Ferrocat adapts their tests, keeps the source of each one, and runs them with its own test suite.

Most cases must parse and match the expected structure. Five must be rejected, because the upstream test expects an error there.

  • polib, the Python PO library88 / 88
  • pofile, the JavaScript PO library301 / 301
  • Babel, Python’s i18n toolkit32 / 32
  • ICU, the official MessageFormat tests32 / 32
  • FormatJS message syntax4 / 4

Source-attributed conformance fixtures, counted by the repository’s conformance harness. Sources, licenses and scope

A focused engine. Your application around it.

Ferrocat is a translation catalog engine. It reads, merges, and compiles translation catalogs. It leaves the rest of internationalization to the tools around it, and you need none of them to use it.

Rust applications and tools
Add the library with cargo add ferrocat and call it directly.
Release checks in CI
Install the command line with cargo install ferrocat-cli and audit on every build.
TypeScript applications
Palamedes, an i18n toolchain for TypeScript apps, runs on Ferrocat. There is no npm package of Ferrocat itself.
Not included
Finding strings in your source code, translating them, or running a translation platform. Those stay with your tools.

gettext taught software to speak in catalogs. Ferrocat carries that model into Git and AI workflows, where merges stay conflict-free and human corrections stay authoritative. Ferrocat continues pofile-ts, its TypeScript predecessor, which stays available as an archived reference. It is one of the Ferramenta engines, made by Sebastian Software in Mainz, Germany.

Put your catalogs in order.

Start with the Rust library, or add the audit to your release pipeline first. Both read the catalogs you already have.

Start with Rustcargo add ferrocatAudit your catalogscargo install ferrocat-cli

GitHub repositoryDocumentationAPI referenceIntegration and support