Rust Applications (Experimental)
Use Palamedes to prepare PO catalogs during a Cargo build, then load the selected language from a file when your Rust CLI or service runs. Every language, including English, stays outside the executable. Compatible translation edits and additional languages can ship without rebuilding it.
Page outline
The Rust SDK is published on crates.io from Palamedes 2.0.0 as palamedes-i18n,
palamedes, and palamedes-build. It is in the Preview tier: the public APIs
follow Cargo SemVer, and Preview describes the feature scope.
The current subset is text, display arguments, string selects, and cardinal and
ordinal plurals. Localized number/date/time formatting, rich text, and translation
contexts are rejected. This path does not yet offer the full TypeScript workflow.
See the stability guide.
Preview and Publication
The Rust SDK is Preview. The runtime, builder, and core compiler ship in the
coordinated Palamedes release set at the shared version; they do not use
separate SDK versions or an independent prerelease publishing channel. The
shared release policy allows only stable v2-or-later versions. Use the same
registry version for palamedes-i18n and palamedes-build.
pnpm verify:rust-sdk packages the three crates in dependency order and inspects
all archive file lists, license texts, READMEs, packaged builds, and rustdoc. A
loopback sparse staging registry serves those exact archives. An independent
project outside the repository uses exact version-only dependencies, a normal
build.rs, and no workspace paths or patches. It runs a copied executable with
external English and German catalogs and an empty PATH, checks plurals and
missing/incompatible errors, then compiles a real PO change with native pmds
against the exported version 2 schema. The application checksum must remain
unchanged. The receipt is target/rust-sdk-proof/receipt.json; temporary consumer
and installation paths are recorded there for inspection.
pnpm release:rust:dry-run runs the same verification without uploading. The
Publish workflow uses it before any publication and CI runs the proof on the
pinned Rust toolchain. Staging matters because the builder depends on SDK
versions that reach crates.io only when the same release uploads them, so a
crates.io publish dry run cannot verify that graph. No archive/build verification
is bypassed.
The prepared Cargo lane publishes palamedes-i18n, then palamedes, then
palamedes-build. It checks exact archive checksums before skipping an existing
version, rejects yanked or different content, and waits a bounded interval for
index visibility before packaging the next crate. Registry authentication or
server errors stop the lane. The lane requires a CRATES_IO_OWNER repository
variable naming a direct owner; it checks existing names against that owner and
repository, and checks ownership after a first upload before continuing to
dependent crates. After every publish job, the workflow reads the crates.io
index again and fails unless all three crates are there, unyanked, at the
release version.
Before any npm or crates.io upload starts, the preflight-cargo job checks the
release policy, the publish = ["crates-io"] allowlists, the configured owner,
that all three crates already exist on crates.io with this repository and
owner, and that the release version is not yanked. It also exchanges the
workflow's OIDC identity for a crates.io token without uploading anything. All
upload jobs depend on it, so a Cargo lane that is not ready stops the release
before npm receives a package. The Cargo upload also waits for every native npm
package, so a failed native build stops crates.io as well as the JavaScript
packages. A Publish dry run runs the same registry checks
without the token exchange. When publication is not enabled, it reports the
policy and allowlists instead of enforcing them.
Cargo publication uses crates.io trusted publishing.
Each crate must trust GitHub Actions for owner sebastian-software, repository
palamedes, workflow publish.yml, with no environment constraint. The
preflight-cargo and publish-cargo jobs grant id-token: write and exchange
their GitHub identity through the commit-pinned rust-lang/crates-io-auth-action.
The preflight passes only whether a token was issued to its readiness check. The
publish job passes its temporary token as CARGO_REGISTRY_TOKEN only to the SDK
upload step. The action revokes each token when its job completes. No long-lived
Cargo secret or token fallback is used. Authentication failure stops
publication; a dry run does not request an OIDC token. A successful exchange
shows that crates.io trusts this workflow for at least one crate. It does not
prove the trusted-publisher configuration of each crate; only the upload does.
Publication needs both publicationEnabled: true in the release policy and
explicit publish = ["crates-io"] allowlists in the three SDK crate manifests.
The CLI, Node binding, and plugin crates keep publish = false. The 0.0.0
bootstrap publications established the crate names and ownership. A passing
dry run does not prove trusted-publisher permissions; only an upload does.
SemVer and MSRV
The crates use the coordinated Palamedes version, and Cargo treats 2.0 to
2.1 as a compatible upgrade. These Rust APIs therefore follow Cargo SemVer:
- the public API of
palamedes-i18n - the public API of
palamedes-build - the
palamedes::sdkmodule, whichpalamedes-buildcompiles catalogs with
Everything else in the palamedes crate is hidden from its rustdoc. It serves
the pmds CLI and the Node binding and can change in any release, so depend on
palamedes-build and palamedes-i18n rather than on palamedes directly.
Items hidden from the palamedes-i18n docs support the generated macro or
describe the catalog file format, which FORMAT_VERSION versions separately.
Because the code palamedes-build generates constructs those hidden items,
palamedes-build requires the exact palamedes-i18n release it ships with
(=2.0.0 for 2.0.0), so Cargo upgrades the two crates together.
palamedes_i18n::Error and palamedes_build::Error are #[non_exhaustive].
New failure kinds can arrive in a minor release, so a match on either error
needs a wildcard arm. Both errors are Send + Sync + 'static and chain I/O,
decoding, and catalog compiler causes through std::error::Error::source.
Data types, such as CompiledCatalogs, stay exhaustive.
The minimum supported Rust version (MSRV) is the rust-version in the
workspace Cargo.toml. A minor release can raise it, with a
changelog entry. The MSRV stays at least two stable Rust releases behind the
latest stable release.
The crates depend on Ferrocat with caret requirements, so your Cargo graph can
resolve a newer compatible Ferrocat release. Palamedes's own builds and tests
use the exact versions in its Cargo.lock.
Build a Small CLI
Create a project with this layout:
greeting-cli/
Cargo.toml
build.rs
locales/
en.po
de.po
src/
main.rs
Use a Rust toolchain compatible with the workspace's rust-version in
Cargo.toml. Use the same version for both crates:
Cargo.toml
[package]
name = "greeting-cli"
version = "0.1.0"
edition = "2024"
[dependencies]
palamedes-i18n = "2.0.0"
[build-dependencies]
palamedes-build = "2.0.0"
Inside the Palamedes workspace, path dependencies are also possible. There is no Node dependency in this Cargo workflow.
locales/en.po
msgid "Hello {name}!"
msgstr "Hello {name}!"
locales/de.po
msgid "Hello {name}!"
msgstr "Hallo {name}!"
The source-language PO defines the complete message inventory and is always an
input. .locales() chooses which language files to emit; it does not require
shipping an English file. Target catalogs may omit entries or contain empty or
fuzzy translations. By default, those entries compile through .fallback_locales()
and ultimately the source locale/message. Cargo reports fallback use; other build
hosts can inspect CompiledCatalogs::missing. Set .fail_on_missing(true) to reject
incomplete target translations. Invalid or unsupported ICU and argument mismatches
still fail compilation. A fallback is compiled into the selected language file;
no source text or fallback language is embedded in the executable.
build.rs
fn main() -> Result<(), Box<dyn std::error::Error>> {
let catalogs = palamedes_build::CatalogBuilder::new("locales", "en")
.locales(&["en", "de"])
.build()?;
catalogs.install_to(std::path::Path::new("dist/translations"))?;
std::fs::copy(&catalogs.schema_file, "dist/schema.pmd.json")?;
Ok(())
}
build() writes generated definitions to OUT_DIR/messages.rs, an exported
message contract to OUT_DIR/schema.pmd.json, and language data to
OUT_DIR/catalogs/<locale>.pmd.json. Keep the schema with your translation-build
inputs; it contains IDs and argument signatures, not translations. The running
application only needs its selected language file. Cargo tracks the input catalogs
and runs this build script when they change. install_to() copies the language
files to a distribution directory chosen by your application. Here that is
dist/translations/ relative to the package root; the build script owns this
output directory, so use a location appropriate to your packaging workflow.
src/main.rs
use std::path::PathBuf;
include!(concat!(env!("OUT_DIR"), "/messages.rs"));
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut arguments = std::env::args().skip(1);
let locale = arguments.next().unwrap_or_else(|| "en".into());
let directory = PathBuf::from(
arguments.next().unwrap_or_else(|| "dist/translations".into()),
);
let catalog = palamedes_i18n::Catalog::load(
directory.join(format!("{locale}.pmd.json")),
&locale,
CATALOG_SCHEMA,
)?;
println!("{}", translate!(&catalog, "Hello {name}!", name = "Ada")?);
Ok(())
}
Run it from the project directory:
cargo run -- de
# Hallo Ada!
cargo run -- en
# Hello Ada!
English is the application's default locale in this example. It still loads
en.pmd.json from disk. A missing English catalog is an error, just like a
missing German one.
Deploy the Executable and Its Language Files
Build the release executable and copy the languages you want to distribute. This POSIX shell example installs only German into a temporary directory:
cargo build --release
install_dir="$(mktemp -d)"
mkdir -p "$install_dir/translations"
cp target/release/greeting-cli "$install_dir/"
cp dist/translations/de.pmd.json "$install_dir/translations/"
(cd "$install_dir" && ./greeting-cli de translations)
# Hallo Ada!
Windows builds produce greeting-cli.exe; copy it and the catalog files with
your platform's packaging tools. Neither installation needs Node, PO files, a
Palamedes checkout, or an English language file to render German.
The application owns locale selection and path discovery. A CLI might inspect
LC_ALL, LC_MESSAGES, and LANG; a service might resolve a locale per request.
The runtime does not read headers or environment variables or search directories.
Pass the selected locale and file path explicitly. Catalogs are immutable, so a
service can keep independent instances per locale and share them across threads.
Catalog::from_bytes(bytes, locale, CATALOG_SCHEMA) supports other storage paths.
What the Generator and Rust Compiler Each Do
- Cargo invokes
build.rsas part ofcargo build.palamedes-builduses Ferrocat's catalog compiler and Palamedes's shared message lowering to prepare language data and generate a schema plus a realmacro_rules! translatedefinition. include!makes those definitions available to your Rust program. Rust's own compiler expandstranslate!calls. It resolves source literals to internal message IDs during constant evaluation and checks named arguments.- The executable loads one prepared catalog and renders its instructions. The runtime decodes JSON data; it contains no PO or ICU parser. No language catalog or source-text rendering fallback is embedded in the executable.
The generator emits one sorted source/signature table and a shared const function
that searches it by binary search. Each macro invocation expands a small lookup,
not a copy of the whole catalog. Both table lookup and argument validation happen
during constant evaluation; the table is not runtime translation storage. If the
generated definitions live inside a module, set .module_path("crate::messages")
to that module's crate-relative path so calls from other modules resolve correctly.
There is no source-rewriting command to run before Cargo. The generator produces
definitions; the normal Rust compiler processes macro invocations. Arguments
can appear in any order. Unknown source messages and missing, extra, or duplicate
argument names fail compilation. A plural or ordinal argument also requires a
built-in integer/float type or a validated PluralNumber; bare strings and other
Display values fail compilation in those positions. Constant messages return Result<&str, Error>;
messages with arguments return Result<String, Error>. Nonplural argument values
implement Display and are inserted literally. Numeric expressions are borrowed
and evaluated once, just like other arguments.
The checked Rust CLI example also shows string selects, plurals, and three languages. Its deployment test copies the executable and selected catalogs into an isolated directory, compiles real PO updates against the exported contract, and adds a compatible language. It checks that the copied executable stays byte-for-byte unchanged.
Plural Messages
Add a complete ICU plural message to the source PO, rather than joining a count
and a translated noun in Rust. For example, append to locales/en.po:
msgid "{count, plural, one {# file} other {# files}}"
msgstr "{count, plural, one {# file} other {# files}}"
Append its translation to locales/de.po:
msgid "{count, plural, one {# file} other {# files}}"
msgstr "{count, plural, one {# Datei} other {# Dateien}}"
Then add a call in main(). Adding a message changes the contract, so rebuild
and redeploy the executable together with its catalogs:
let count = 2_usize;
println!(
"{}",
translate!(&catalog, "{count, plural, one {# file} other {# files}}", count = count)?
);
// With the German catalog: 2 Dateien
plural uses the selected catalog locale's CLDR cardinal rules; selectordinal
uses its ordinal rules. ICU4X caches the required rule sets when the catalog
loads. Its compiled CLDR rule data is part of the runtime dependency; translated
messages remain external. Regional locales such as pt-PT and pt-BR retain
their own rules. Supply the categories your translation needs: zero, one,
two, few, many, and the required other. A missing category selects other.
Exact branches such as =0 match the original count before category selection.
With offset:1, category selection and # use the count minus one. A # inside
a nested select keeps the enclosing plural's value; a nested plural supplies
its own value. An apostrophe-quoted '#' remains literal text.
The generated signature distinguishes display arguments from numeric plural and
ordinal arguments. Built-in integers and floating-point values, including borrowed
values, work directly. A call such as count = "drei" fails Rust compilation,
as do bare decimal strings. Ordinary text and select arguments still accept
Display values.
For decimal input that must preserve visible fractional zeros, parse it into
PluralNumber before calling the macro:
let count: palamedes_i18n::PluralNumber = "1.0".parse()?;
println!(
"{}",
translate!(&catalog, "{count, plural, one {# file} other {# files}}", count = count)?
);
PluralNumber validates the signed plain decimal and preserves its visible
digits. English "1" selects one, while "1.0" selects other. A floating-point
value whose Rust display is 1 consequently selects one. The numeric range
remains at most 18 fractional digits and an i128 coefficient, including after
offset subtraction. Invalid decimal input fails parsing. Non-finite floats,
exponent notation, out-of-range numeric values, and arithmetic overflow can still
return Error::PluralArgument at rendering time; type checking cannot prove those
value constraints. Counts are never rounded through f64.
Translations and independent catalog updates cannot introduce a plural for an argument that the source message only uses as display/select text. Such a change would impose a new numeric requirement on existing callers, so compilation and catalog loading reject it. Translations may simplify a numeric argument to plain display without weakening the source contract.
# emits the adjusted value as plain decimal text, preserving fractional zeros.
It does not add localized grouping, separators, or digits. {count, number} and
number/date/time styles remain unsupported; format those values in the host
application when needed.
Update Translations Without Building the Application
Use the native pmds CLI from the same Palamedes release as your crates, for
example @palamedes/cli 2.0.0; the 1.x CLI does not have this command. Its own
external UI catalogs must be installed alongside it.
The update command itself does not invoke Cargo or rustc for your application.
After the initial application build, change the greeting entry in locales/de.po
to the following, keeping any other entries:
msgid "Hello {name}!"
msgstr "Guten Tag {name}!"
Compile that PO file against the already exported contract:
pmds catalog compile --target rust \
--schema dist/schema.pmd.json \
--catalog-dir locales --locale de \
--output dist/translations
This writes only de.pmd.json, checks the schema fingerprint and full message
contract, and leaves other installed locales in the output directory alone.
Keep en.po as the source-inventory input. Repeat --locale for multiple output
languages; a new language uses the same workflow with its own <locale>.po file.
Use --fallback-locale to configure the build-time chain, --fail-on-missing for
strict completeness, or --json for the output paths and missing-translation
report. Invalid or changed contracts fail before any output catalog is replaced.
Each accepted language file is replaced atomically.
With the install_dir created in the deployment example, install the new data
and run the same copied executable:
cp dist/translations/de.pmd.json "$install_dir/translations/"
(cd "$install_dir" && ./greeting-cli de translations)
# Guten Tag Ada!
No application build belongs between those two runs. The equivalent Rust tooling
API loads CatalogContract::load(schema_path) and calls
CatalogBuilder::compile_updates(&contract, output_directory).
Catalog Compatibility and Failures
Plural and pound instructions use compiled format version 2. Version 1 artifacts
and exported schemas must be regenerated with the matching builder, runtime,
and pmds implementation. Upgrade the executable and its catalogs together once;
compatible PO updates can then continue using the exported version 2 schema.
Each catalog carries a format version, locale, and fingerprint of message IDs and argument signatures. Loading checks those fields, the complete message inventory, and the prepared instruction signatures. The Rust data format is separate from the JavaScript catalog ABI.
You can replace translated text or add a locale without rebuilding the executable as long as the message contract stays compatible. Generate new language files from the same message inventory and signatures using the exported schema. The source PO remains an input even when no source-language file is emitted. Adding or removing messages or changing their argument contract requires matching catalogs and an application build.
A missing, corrupt, wrong-locale, or incompatible file returns an error.
Catalog::load() attaches the file path to all failures and distinguishes format
version, locale, and contract-fingerprint mismatches. There is no automatic retry in English and no source-text substitution. The small example
above exits through Rust's normal Result error reporting. A production host
should choose its own bootstrap diagnostic and exit or request-error policy.
Extraction and Current Limits
palamedes_build::extract_messages(source, macro_name) extracts source literals
and line numbers from Rust token trees, including calls inside attributes. It
ignores comments and ordinary string contents and rejects dynamic source
expressions. It is an API for Rust tooling. pmds extract does not yet extract
Rust sources; its existing inputs remain JavaScript, TypeScript, and MDX.
The small example above maintains its PO entries directly.
| Message feature | Experimental Rust support |
|---|---|
| Literal text | Supported |
| Named display arguments | Supported; names checked, numeric plural types enforced by Rust |
| String selects | Supported |
| Plurals and ordinal plurals | Supported; CLDR categories, exact branches, offsets, and # |
| Localized numbers, dates, and times | Rejected at build time |
| Rich text and translation contexts | Rejected at build time |
Palamedes's own pmds CLI uses this integration for external English, German, Spanish, and
French catalogs. Its environment precedence, installation layout, and diagnostic
boundaries are documented in CLI output language.
Those are policies of pmds, not defaults imposed on your application.