PhoenixKit.Module.Languages (phoenix_kit v1.5.1)

Languages management for PhoenixKit - complete language configuration in a single module.

This module provides management for language module in PhoenixKit applications. It handles language configuration, settings, and language data through JSON settings.

Language Structure

Each language has the following structure:

code: Language code (e.g., "en", "es", "fr")
name: Full language name (e.g., "English", "Spanish", "French")
is_default: Boolean indicating if this is the default language
is_enabled: Boolean indicating if this language is active

Core Functions

Languages Management

enabled?/0 - Check if languages are enabled
enable_system/0 - Enable languages with default English
disable_system/0 - Disable languages
get_config/0 - Get complete configuration

Language Management

get_languages/0 - Get all configured languages
get_enabled_languages/0 - Get only enabled languages
get_default_language/0 - Get the default language
get_language/1 - Get a specific language by code
get_language_codes/0 - Get list of all language codes
get_enabled_language_codes/0 - Get list of enabled language codes
valid_language?/1 - Check if a language code exists
language_enabled?/1 - Check if a language is enabled
add_language/1 - Add a new language to the system
update_language/2 - Update an existing language
remove_language/1 - Remove a language from the system
set_default_language/1 - Set a new default language
enable_language/1 - Enable a specific language
disable_language/1 - Disable a specific language

Usage Examples

# Check if languages are enabled
if PhoenixKit.Module.Languages.enabled?() do
  # Languages are active
end

# Enable languages (creates default English language)
{:ok, config} = PhoenixKit.Module.Languages.enable_system()

# Add a new language
{:ok, config} = PhoenixKit.Module.Languages.add_language("es")

# Get all languages
languages = PhoenixKit.Module.Languages.get_languages()
# => [%{code: "en", name: "English", is_default: true, is_enabled: true}, ...]

# Get only enabled languages (most common use case)
enabled_languages = PhoenixKit.Module.Languages.get_enabled_languages()
# => [%{code: "en", name: "English", ...}, %{code: "es", name: "Spanish", ...}]

# Get a specific language by code
spanish = PhoenixKit.Module.Languages.get_language("es")
# => %{code: "es", name: "Spanish", is_enabled: true}

# Get just the language codes
codes = PhoenixKit.Module.Languages.get_enabled_language_codes()
# => ["en", "es", "fr"]

# Check if a language is valid and enabled
if PhoenixKit.Module.Languages.language_enabled?("es") do
  # Use Spanish language
end

JSON Storage Format

Languages are stored in the languages_config setting as JSON. The array order determines the display order:

{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "is_default": true,
      "is_enabled": true
    },
    {
      "code": "es",
      "name": "Spanish",
      "is_default": false,
      "is_enabled": true
    }
  ]
}

Summary

Functions

add_language(code)

Adds a predefined language to the module by language code.

disable_language(code)

Disables a specific language.

disable_system()

Disables the language module.

enable_language(code)

Enables a specific language.

enable_system()

Enables the language module and creates default configuration.

enabled?()

Checks if the language module is enabled.

enabled_locale_codes()

Gets enabled language codes for locale-based routing.

get_available_languages()

Gets all available predefined languages.

get_available_languages_for_selection()

Gets available languages for selection (excludes already added languages).

get_config()

Gets the complete language module configuration.

get_default_language()

Gets the default language.

get_enabled_language_codes()

Gets a list of enabled language codes, sorted by position.

get_enabled_languages()

Gets only enabled languages, sorted by position.

get_language(code)

Gets a specific language by its code.

get_language_codes()

Gets a list of all language codes.

get_languages()

Gets all configured languages from the JSON setting.

get_predefined_language(code)

Gets a predefined language by code.

language_enabled?(code)

Checks if a language is enabled.

move_language_down(code)

Moves a language down one position in the array.

move_language_up(code)

Moves a language up one position in the array.

remove_language(code)

Removes a language from the system.

set_default_language(code)

Sets a new default language.

update_language(code, attrs)

Updates an existing language in the system.

valid_language?(code)

Checks if a language code is valid (exists in configuration).

Functions

add_language(code)

Adds a predefined language to the module by language code.

Takes a language code and adds the corresponding predefined language to the module configuration. Only languages from the predefined list can be added.

Examples

iex> PhoenixKit.Module.Languages.add_language("es")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.add_language("en")  # if already exists
{:error, "Language already exists"}

iex> PhoenixKit.Module.Languages.add_language("invalid")
{:error, "Language not found in available languages"}

disable_language(code)

Disables a specific language.

Cannot disable the default language.

Examples

iex> PhoenixKit.Module.Languages.disable_language("es")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.disable_language("en")  # if it's default
{:error, "Cannot disable default language"}

disable_system()

Disables the language module.

Turns off the language module but preserves the language configuration.

Returns {:ok, setting} on success, {:error, changeset} on failure.

Examples

iex> PhoenixKit.Module.Languages.disable_system()
{:ok, %Setting{}}

enable_language(code)

Enables a specific language.

Examples

iex> PhoenixKit.Module.Languages.enable_language("es")
{:ok, updated_config}

enable_system()

Enables the language module and creates default configuration.

Creates the initial module configuration with English as the default language. Updates both the enabled flag and the JSON configuration.

Returns {:ok, config} on success, {:error, reason} on failure.

Examples

iex> PhoenixKit.Module.Languages.enable_system()
{:ok, %{"languages" => [%{"code" => "en", ...}]}}

enabled?()

Checks if the language module is enabled.

Returns true if the module is enabled, false otherwise.

Examples

iex> PhoenixKit.Module.Languages.enabled?()
false

enabled_locale_codes()

Gets enabled language codes for locale-based routing.

Returns a list of enabled language codes that can be used in URL routing. Falls back to ["en"] when the language module is disabled.

Examples

iex> PhoenixKit.Module.Languages.enabled_locale_codes()
["en", "es", "fr"]

# When system is disabled:
iex> PhoenixKit.Module.Languages.enabled_locale_codes()
["en"]

get_available_languages()

Gets all available predefined languages.

Returns the complete list of languages that can be added to the system. This list is used to populate dropdown selections.

Examples

iex> PhoenixKit.Module.Languages.get_available_languages()
[%{code: "en", name: "English", native: "English", flag: "🇺🇸"}, ...]

get_available_languages_for_selection()

Gets available languages for selection (excludes already added languages).

Returns languages that can be added to the system, filtered to exclude languages that have already been configured.

Examples

iex> PhoenixKit.Module.Languages.get_available_languages_for_selection()
[%{code: "es", name: "Spanish", native: "Español", flag: "🇪🇸"}, ...]

get_config()

Gets the complete language module configuration.

Returns a map with module status and language configuration.

Examples

iex> PhoenixKit.Module.Languages.get_config()
%{
  enabled: true,
  languages: [%{"code" => "en", "name" => "English", ...}],
  language_count: 1,
  enabled_count: 1,
  default_language: %{"code" => "en", "name" => "English", ...}
}

get_default_language()

Gets the default language.

Returns the language map marked as default, or nil if none found.

Examples

iex> PhoenixKit.Module.Languages.get_default_language()
%{"code" => "en", "name" => "English", "is_default" => true, ...}

# When system is disabled:
iex> PhoenixKit.Module.Languages.get_default_language()
nil

get_enabled_language_codes()

Gets a list of enabled language codes, sorted by position.

Returns a list of enabled language code strings.

Examples

iex> PhoenixKit.Module.Languages.get_enabled_language_codes()
["en", "es"]

get_enabled_languages()

Gets only enabled languages, sorted by position.

Returns a list of enabled language maps.

Examples

iex> PhoenixKit.Module.Languages.get_enabled_languages()
[%{"code" => "en", "name" => "English", ...}]

get_language(code)

Gets a specific language by its code.

Returns the language map if found, or nil if not found.

Examples

iex> PhoenixKit.Module.Languages.get_language("es")
%{"code" => "es", "name" => "Spanish", "is_enabled" => true}

iex> PhoenixKit.Module.Languages.get_language("invalid")
nil

get_language_codes()

Gets a list of all language codes.

Returns a list of language code strings.

Examples

iex> PhoenixKit.Module.Languages.get_language_codes()
["en", "es", "fr"]

get_languages()

Gets all configured languages from the JSON setting.

Returns a list of language maps, or empty list if not configured.

Examples

iex> PhoenixKit.Module.Languages.get_languages()
[%{"code" => "en", "name" => "English", "is_default" => true, ...}]

# When system is disabled:
iex> PhoenixKit.Module.Languages.get_languages()
[]

get_predefined_language(code)

Gets a predefined language by code.

Returns the language definition from the available languages list.

Examples

iex> PhoenixKit.Module.Languages.get_predefined_language("es")
%{code: "es", name: "Spanish", native: "Español", flag: "🇪🇸"}

iex> PhoenixKit.Module.Languages.get_predefined_language("invalid")
nil

language_enabled?(code)

Checks if a language is enabled.

Returns true if the language exists and is enabled, false otherwise.

Examples

iex> PhoenixKit.Module.Languages.language_enabled?("es")
true

iex> PhoenixKit.Module.Languages.language_enabled?("disabled_lang")
false

move_language_down(code)

Moves a language down one position in the array.

Moves the language one index later in the languages array. Cannot move the last language down.

Examples

iex> PhoenixKit.Module.Languages.move_language_down("en")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.move_language_down("es")  # if last in array
{:error, "Language is already at the bottom"}

move_language_up(code)

Moves a language up one position in the array.

Moves the language one index earlier in the languages array. Cannot move the first language up.

Examples

iex> PhoenixKit.Module.Languages.move_language_up("es")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.move_language_up("en")  # if first in array
{:error, "Language is already at the top"}

remove_language(code)

Removes a language from the system.

Cannot remove the default language or the last remaining language.

Examples

iex> PhoenixKit.Module.Languages.remove_language("es")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.remove_language("en")  # if it's default
{:error, "Cannot remove default language"}

set_default_language(code)

Sets a new default language.

Removes default status from all other languages and sets the specified language as default.

Examples

iex> PhoenixKit.Module.Languages.set_default_language("es")
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.set_default_language("nonexistent")
{:error, "Language not found"}

update_language(code, attrs)

Updates an existing language in the system.

Takes a language code and map of attributes to update.

Examples

iex> PhoenixKit.Module.Languages.update_language("es", %{name: "Español"})
{:ok, updated_config}

iex> PhoenixKit.Module.Languages.update_language("nonexistent", %{name: "Test"})
{:error, "Language not found"}

valid_language?(code)

Checks if a language code is valid (exists in configuration).

Returns true if the language exists, false otherwise.

Examples

iex> PhoenixKit.Module.Languages.valid_language?("es")
true

iex> PhoenixKit.Module.Languages.valid_language?("invalid")
false