@palamedes/core

Exports

• createI18n()
• formatMessagePattern(pattern, values, locale?)
• parseMessagePattern(pattern)
• parseAcceptLanguage(header) from @palamedes/core/locale
• buildLocaleSwitchItems(options) from @palamedes/core/locale
• defineLocaleControls(config) from @palamedes/core/locale
• MessageDescriptor
• CatalogMessages
• PalamedesI18n
• CreateI18nOptions
• MissingMessageInfo
• MessageFormatErrorInfo
• MessageNode
• MessageChoiceNode
• MessageFormattedArgumentNode
• MessageTagNode
• MessageVariableNode

createI18n()

Creates an in-memory i18n instance. Optional telemetry hooks receive missing message and runtime formatting failures without changing the source-message fallback behavior.

import { createI18n } from "@palamedes/core"

const i18n = createI18n({
  onMissing(info) {
    reportMetric("palamedes.missing", info)
  },
  onError(info) {
    captureException(info.error)
  },
})
i18n.load("de", {
  "Hello {name}": "Hallo {name}",
})
i18n.activate("de")

const label = i18n._("Hello {name}", { name: "Ada" })

PalamedesI18n

interface PalamedesI18n {
  locale?: string
  _(idOrDescriptor, values?, descriptor?): string
  load(locale: string, messages: CatalogMessages): void
  activate(locale: string): void
  getMessage(id: string, descriptor?: MessageDescriptor): string
}

load() merges messages into the locale catalog. activate() selects the locale used by _() and getMessage().

Fallback order for getMessage(id, descriptor):

1. active catalog entry for id
2. descriptor.message
3. id

MessageDescriptor

interface MessageDescriptor {
  id?: string
  message?: string
  context?: string
  comment?: string
}

Palamedes source authoring is source-string-first. Use context when the same source message needs different translations in different UI contexts.

Locale Controls

@palamedes/core/locale exposes headless locale helpers used by the example matrix and reusable in apps:

• parseAcceptLanguage(header): parses and quality-sorts Accept-Language tags, including base-language fallbacks.
• buildLocaleSwitchItems(options): builds UI-agnostic switch items with labels, active state, locale, and test ids.
• defineLocaleControls(config): binds locale resolution, deliberate-choice cookies, canonical URLs, and suggestion decisions for cookie, route, subdomain, and tld strategies.

Macro Entry Point

Macros are imported from @palamedes/core/macro and must be compiled by a Palamedes plugin before runtime.

Supported macro names:

• t
• msg
• defineMessage
• plural
• select
• selectOrdinal

Runtime Formatting

formatMessagePattern() and createI18n()._() support the formatter subset implemented by the Palamedes runtime:

• {value, number}
• {value, number, percent} and {value, number, integer}
• {value, number, ::percent}, {value, number, ::integer}, and {value, number, ::currency/ISO}
• {value, date} and {value, time}
• {value, date, short|medium|long|full}
• {value, time, short|medium|long|full}

Currency formatting must use the ::currency/ISO skeleton form; bare currency/ISO is outside the supported runtime subset.

Catalog artifact compilation reports list, duration, ago, name, and other unsupported formatter kinds as errors. Unsupported styles on number, date, and time are warnings because the runtime currently falls back to the default Intl formatter for that argument type.