@spec get_translation(map(), String.t()) :: map()

Gets translated field data for a record in a specific language. Returns merged data (primary language as base + overrides for the requested language).

@spec localize(list(), String.t() | nil) :: list()

Replaces :name (and :description where present) on each record with the locale-resolved display text, so list/detail surfaces can render record.name untouched and still honor the viewer's locale.

Resolve-early by design (the same shape as resolved_group/2): the alternative — threading a locale attr through every table/tile/cell component — spreads the concern across dozens of render sites. Records without a :data map (folders) pass through unchanged, as does everything when locale is nil. Struct identity is preserved (%{record | ...}), and mutations are unaffected: status/move/ reorder writes never take :name from these list structs.

@spec localize_one(map() | nil, String.t() | nil) :: map() | nil

Single-record localize/2.

@spec set_translation(map(), String.t(), map(), function(), keyword()) ::
  {:ok, term()} | {:error, term()}

Updates the multilang data field for a record with language-specific field data. For primary language: stores ALL fields. For secondary languages: stores only overrides (differences from primary).

update_fn is the entity's update function. It receives (record, attrs) for 2-arity or (record, attrs, opts) for 3-arity when activity-logging opts are provided.

@spec translated_description(map() | nil, String.t() | nil) :: String.t() | nil

Same contract as translated_name/2, for :description.

@spec translated_name(map() | nil, String.t() | nil) :: String.t() | nil

The display name for locale: the locale's translation override (either the "_name" shape the shared multilang helper writes or the legacy bare "name"), falling back to the primary-language column. Safe on records without translations and on plain maps.