Migrating To Palamedes 1.0

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-fcl

git config merge.palamedes-catalog.name "Palamedes catalog merge"
git config merge.palamedes-catalog.driver \
  'pmds catalog merge --format=po --conflict-strategy=use-first --base %O --output %A %A %B'

git config merge.palamedes-catalog-fcl.name "Palamedes FCL catalog merge"
git config merge.palamedes-catalog-fcl.driver \
  'pmds catalog merge --format=fcl --conflict-strategy=use-first --base %O --output %A %A %B'

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

Conversion fails before writing output when a PO source contains raw fuzzy flags. Reverse FCL-to-PO conversion is not part of 1.0.

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

• CatalogFileFormat no longer accepts ndjson.
• Native catalog format enums expose Po | Fcl.
• TypeScript wrapper APIs expose "po" | "fcl".
• fuzzyFlags and fuzzy report columns are removed.

More Detail

• Catalog formats
• CLI reference
• Configuration reference
• Stability and versioning