PhoenixKit.Modules.Entities.Multilang (phoenix_kit v1.7.71)

Multi-language data transformation helpers for entity data JSONB.

Multi-language support is driven by the Languages module globally. When the Languages module is enabled and has more than one language, all entities automatically support multilang data. There is no per-entity toggle — languages are configured system-wide.

The data JSONB column stores a nested structure:

%{
  "_primary_language" => "en-US",
  "en-US" => %{"_title" => "Acme", "name" => "Acme", "tagline" => "Quality products"},
  "es-ES" => %{"_title" => "Acme España", "name" => "Acme España"}
}

The primary language always has complete data. Secondary languages store only overrides — fields that differ from primary. Display merges primary values as defaults with language-specific overrides.

The _title key stores the record title alongside custom fields, unifying title translation with the same override-only storage pattern. The title DB column remains a denormalized copy for queries/sorting.

Summary

Functions

build_language_tabs()

Builds language tab data for the UI from the Languages module. Returns a list of maps with code, name, flag, and is_primary fields.

enabled?()

Checks if multilang is enabled globally. Returns true when the Languages module is enabled and has more than one language.

enabled_languages()

Gets the list of enabled language codes. Returns at minimum the primary language.

flatten_to_primary(data)

Converts multilang data back to flat structure. Returns primary language data.

get_language_data(data, lang_code)

Extracts the data map for a specific language from a record's data.

get_primary_data(data)

Gets the primary language data from a record (for display in lists etc).

get_raw_language_data(data, lang_code)

Gets raw (non-merged) language-specific data for a language. Used by the form UI to detect which fields are overridden vs inherited.

maybe_rekey_data(data)

Checks if data needs re-keying (embedded primary != global primary). Returns re-keyed data if needed, original data otherwise.

migrate_to_multilang(flat_data, primary_lang)

Converts existing flat data to multilang structure.

multilang_data?(data)

Checks if a data map uses the multilang structure. Presence of _primary_language key indicates multilang.

primary_language()

Gets the primary (default) language code. Returns the Languages module default, falling back to "en-US".

put_language_data(existing_data, lang_code, new_field_data)

Merges language-specific form data into the full multilang JSONB.

rekey_primary(data, new_primary)

Re-keys multilang data to a new primary language.

Functions

build_language_tabs()

@spec build_language_tabs() :: [map()]

Builds language tab data for the UI from the Languages module. Returns a list of maps with code, name, flag, and is_primary fields.

enabled?()

@spec enabled?() :: boolean()

Checks if multilang is enabled globally. Returns true when the Languages module is enabled and has more than one language.

enabled_languages()

@spec enabled_languages() :: [String.t()]

Gets the list of enabled language codes. Returns at minimum the primary language.

flatten_to_primary(data)

@spec flatten_to_primary(map() | nil) :: map()

Converts multilang data back to flat structure. Returns primary language data.

get_language_data(data, lang_code)

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

Extracts the data map for a specific language from a record's data.

For multilang data: returns merged data (primary as base + overrides). For flat data: returns data as-is (backward compat).

get_primary_data(data)

@spec get_primary_data(map() | nil) :: map()

Gets the primary language data from a record (for display in lists etc).

get_raw_language_data(data, lang_code)

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

Gets raw (non-merged) language-specific data for a language. Used by the form UI to detect which fields are overridden vs inherited.

maybe_rekey_data(data)

@spec maybe_rekey_data(map() | nil) :: map() | nil

Checks if data needs re-keying (embedded primary != global primary). Returns re-keyed data if needed, original data otherwise.

migrate_to_multilang(flat_data, primary_lang)

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

Converts existing flat data to multilang structure.

multilang_data?(data)

@spec multilang_data?(map() | nil) :: boolean()

Checks if a data map uses the multilang structure. Presence of _primary_language key indicates multilang.

primary_language()

@spec primary_language() :: String.t()

Gets the primary (default) language code. Returns the Languages module default, falling back to "en-US".

put_language_data(existing_data, lang_code, new_field_data)

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

Merges language-specific form data into the full multilang JSONB.

For primary language: stores ALL fields. For secondary language: stores only fields that differ from primary.

rekey_primary(data, new_primary)

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

Re-keys multilang data to a new primary language.

Updates _primary_language to the new primary and ensures the new primary has complete data (fills missing fields from the old primary). All secondary languages are recomputed: their overrides are recalculated against the new promoted primary, and languages with zero overrides are removed.

Returns data unchanged if already using the given primary or not multilang.