Skip to content

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 machine shape.
  • 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

  • PalamedesCatalogFormat no longer accepts ndjson.
  • Native catalog format enums expose Po | Fcl.
  • TypeScript wrapper APIs expose "po" | "fcl".
  • Palamedes 1.0 removed fuzzyFlags and fuzzy report columns. Current releases expose both again through Ferrocat's format-neutral review semantics.

More Detail

Edit this page on GitHubLast updated: November 10, 2026