Migrating To Palamedes 1.0
Palamedes 1.0 ships the Ferrocat 2.x catalog migration as the stabilization release for the public app-facing surface. The runtime authoring model stays source-string-first, but catalog storage, metadata, and cleanup semantics now follow Ferrocat 2.x.
Page outline
Summary
- PO remains the default catalog storage format.
- FCL is the new opt-in generated storage format for canonical, merge-friendly catalogs.
- NDJSON catalog surfaces have been removed instead of kept as a compatibility shim.
- Catalog origins no longer serialize source line numbers; stable scope anchors are stored separately when extraction can infer them.
- Machine-translation metadata now uses Ferrocat's
machineshape. - Fuzzy report semantics have been removed.
- Obsolete cleanup is age-aware by default.
Config
Keep PO storage by omitting format:
catalogs:
- path: src/locales/{locale}
include: [src]
Opt into FCL storage:
catalogs:
- path: src/locales/{locale}
format: fcl
include: [src]
Replace any old NDJSON config:
catalogs:
- path: src/locales/{locale}
- format: ndjson
+ format: fcl
include: [src]
Existing format: ndjson configs now fail with a diagnostic that points to
format: fcl.
Catalog Files And Merge Drivers
Remove old NDJSON gitattributes and merge-driver entries such as:
*.ndjson merge=palamedes-catalog
*.fcat.ndjson merge=palamedes-catalog
Use PO and FCL drivers instead:
*.po merge=palamedes-catalog
*.fcl merge=palamedes-catalog
git config merge.palamedes-catalog.name "Palamedes catalog merge"
git config merge.palamedes-catalog.driver \
'pmds catalog merge-driver %O %A %B %A --path %P --conflict-strategy=use-first'
The same driver handles both extensions: %P is the tracked logical pathname,
so Palamedes infers PO or FCL before inspecting Git's extensionless temporary
files. Pass --format=po or --format=fcl only when intentionally overriding
that pathname.
Converting PO To FCL
Convert one catalog:
pmds catalog convert src/locales/de.po --to fcl --output src/locales/de.fcl
Convert every configured PO catalog:
pmds catalog convert --config palamedes.yaml --to fcl
Palamedes 1.0 originally rejected PO catalogs containing raw fuzzy flags.
Current releases preserve those review markers when converting to FCL.
Reverse FCL-to-PO conversion is not exposed by the Palamedes CLI.
Metadata Shape
Machine metadata is exposed as:
type MachineMetadata = {
lock: string;
ai?: {
model: string;
confidence?: number;
};
};
Replace old machineTranslation consumers with machine. AI confidence is a
number in 0..1.
Parsed origins now use:
type ParsedCatalogOrigin = {
file: string;
scope?: string;
};
Catalog update inputs still carry extraction line data for deterministic writes:
type CatalogOrigin = {
file: string;
line: number;
scope?: string;
};
Line numbers remain extraction-internal for diagnostics and deterministic sorting. They are not serialized into catalogs.
CLI Cleanup Semantics
pmds extract --clean now removes only obsolete entries whose
obsolete-since date is at least 30 days old. Undated obsolete entries are kept.
pmds extract --force-clean removes obsolete entries immediately, including
undated entries.
API Removals
PalamedesCatalogFormatno longer acceptsndjson.- Native catalog format enums expose
Po | Fcl. - TypeScript wrapper APIs expose
"po" | "fcl". - Palamedes 1.0 removed
fuzzyFlagsand fuzzy report columns. Current releases expose both again through Ferrocat's format-neutral review semantics.