PhoenixKitStaff.L10n (PhoenixKitStaff v0.3.0)

Copy Markdown View Source

Tiny locale-aware date/time formatting helpers used by the staff UI.

Unlike Calendar.strftime(d, "%b %d, %Y"), the output of these helpers is safe to translate: the three-letter month labels and the surrounding string template all go through Gettext, so a German locale produces 15. Jan 2025 (or whatever the translator wrote) instead of a hardcoded English ordering.

The function bodies intentionally list every month as a separate gettext/1 call so the string-extraction task picks up all 12 labels into the .pot file. Don't collapse them into a map-based lookup.

Summary

Functions

format_date(dt)

Formats a Date/DateTime as Mon DD, YYYY. Returns nil for nil.

format_month_day(dt)

Formats as Mon DD (no year). Useful for near-term dates.

localized_field(record, field, lang)

Reads a translatable field (a DB-column name string) off record in the requested lang, with primary-fallback semantics: a missing or empty ("") language override returns the primary-column value. lang may be nil (multilang disabled), in which case the primary column is returned directly. Shared by every staff schema's localized_<field>/2 helpers.

short_month(int)

Short 3-letter month name, translated (Jan, Feb, ...).

valid_translations_shape?(map)

True when translations matches the documented JSONB shape

validate_translations(changeset)

Changeset guard for a translations JSONB column. When the cast produced a :translations change that doesn't match valid_translations_shape?/1, adds an error; otherwise returns the changeset untouched. Shared by every staff schema so the shape contract lives in one place.

Functions

format_date(dt)

@spec format_date(Date.t() | DateTime.t() | NaiveDateTime.t() | nil) ::
  String.t() | nil

Formats a Date/DateTime as Mon DD, YYYY. Returns nil for nil.

format_month_day(dt)

@spec format_month_day(Date.t() | DateTime.t() | nil) :: String.t() | nil

Formats as Mon DD (no year). Useful for near-term dates.

localized_field(record, field, lang)

@spec localized_field(struct(), String.t(), String.t() | nil) :: String.t() | nil

Reads a translatable field (a DB-column name string) off record in the requested lang, with primary-fallback semantics: a missing or empty ("") language override returns the primary-column value. lang may be nil (multilang disabled), in which case the primary column is returned directly. Shared by every staff schema's localized_<field>/2 helpers.

short_month(int)

@spec short_month(1..12) :: String.t()

Short 3-letter month name, translated (Jan, Feb, ...).

valid_translations_shape?(map)

@spec valid_translations_shape?(any()) :: boolean()

True when translations matches the documented JSONB shape:

%{optional(String.t()) => %{optional(String.t()) => String.t()}}

i.e. an outer map keyed by language code ("es-ES") whose values are maps keyed by translatable field name ("name") with string values. %{} and nil are valid (empty / unset). Used by every staff schema with a translations column so a programmatic caller can't persist garbage that the read helpers would silently fall back through.

Same contract as PhoenixKitProjects.L10n.valid_translations_shape?/1.

validate_translations(changeset)

@spec validate_translations(Ecto.Changeset.t()) :: Ecto.Changeset.t()

Changeset guard for a translations JSONB column. When the cast produced a :translations change that doesn't match valid_translations_shape?/1, adds an error; otherwise returns the changeset untouched. Shared by every staff schema so the shape contract lives in one place.