# `PhoenixKit.Utils.Multilang`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.164/lib/phoenix_kit/utils/multilang.ex#L1)

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.

# `build_language_tabs`

```elixir
@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?`

```elixir
@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`

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

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

# `flatten_to_primary`

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

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

# `get_language_data`

```elixir
@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`

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

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

# `get_raw_language_data`

```elixir
@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`

```elixir
@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`

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

Converts existing flat data to multilang structure.

# `multilang_data?`

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

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

# `primary_language`

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

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

# `put_language_data`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*