@palamedes/config

Lean config loading for Palamedes projects.

Use @palamedes/config when framework integrations need to load Palamedes config files. It supports canonical palamedes.yaml files, secondary palamedes.yml, palamedes.json, and palamedes.toml data files, and the legacy palamedes.config.ts/js/mjs/cjs TypeScript/JavaScript formats.

Minimal Example

locales: [en, de]
source-locale: en
source-reference-root: git
catalogs:
  - path: src/locales/{locale}
    include: [src]
    po:
      line-breaks: "off"

PO output options are per catalog. In JavaScript or TypeScript configs, use po: { lineBreaks }; data configs use the kebab-case spelling shown above. Catalog order is not configurable — Ferrocat gives PO and FCL catalogs the CLDR root order matching Intl.Collator("en-US"). The po object is invalid for FCL catalogs.

Exports

• defineConfig(config)
• loadPalamedesConfig(options?)
• loadPalamedesConfigSync(options?) — synchronous variant with the same options and return shape, for hosts that cannot await (e.g. synchronous loader hooks)
• CONFIG_FILENAMES
• expandFallbackLocales(locales, fallbackLocales?)
• resolveCatalogPath(config, catalogPath, locale)
• resolveConfigPattern(config, pattern)
• PalamedesPluginDeclaration (TypeScript)

Configuration Notes

• fallback-locales defines the fallback chain for missing translations. It can be one shared array or a per-locale map.
• pseudo-locale marks a generated pseudo-locale used for layout and hardcoded string checks. Plugin integrations skip failOnMissing failures for that locale while keeping strict checks for real locales.
• source-reference-root controls the root used for catalog source references. The default is "git", which emits paths relative to the nearest Git repository root and falls back to the config directory when no Git root is available. Use "lingui" or "config" for Lingui-compatible references relative to the config directory, or pass a custom path.
• reference-scopes defaults to true. Set it to false to skip stable component/function scope extraction and emit file-only PO and FCL references.
• catalogs[].format defaults to "po". Set it to "fcl" to use Ferrocat Catalog Lines for canonical, merge-friendly generated catalog storage.
• plugins explicitly lists CLI plugin package specifiers or [specifier, options] pairs. Packages are never auto-discovered, and built-in CLI commands do not load them.
• loadPalamedesConfig() returns sourceReferenceRoot and the resolved referenceScopes boolean in addition to configPath and rootDir. Its configDependencies array contains real paths for the config and every local file imported by a legacy executable config. Framework integrations use this list for cache invalidation and file watching. Pass skipValidation only when inspecting a partially-authored config file.

See Catalog formats for the PO/FCL storage boundary.

See Pseudo-localization and fallback locales for examples and the recommended development workflow.

palamedes is part of the Ferramenta family — Rust-native developer tools that keep the APIs the ecosystem already knows.

Siblings: ferroni · ferriki · ferromark · ferrolex · ferrocat · ferrovia · ferralk · ferrugo.

License

MIT OR Apache-2.0 © 2026 Sebastian Software