@spec base_language_code?(String.t() | any()) :: boolean()

Returns true for bare base language codes like "en" or "de".

@spec build_language_entry(String.t(), map(), [String.t()], String.t() | nil) :: map()

Builds a single language entry map for a post.

Builds language data for a post's language switcher. Returns a list of language maps with status, enabled flag, known flag, and metadata.

@spec default_language_no_prefix?() :: boolean()

Returns true when public URLs should omit the prefix for the default language.

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

Returns all enabled language codes for multi-language support. Falls back to content language if Languages module is disabled.

@spec get_display_code(String.t(), [String.t()]) :: String.t()

Determines the display code for a language based on whether multiple dialects of the same base language are enabled.

If only one dialect of a base language is enabled (e.g., just "en-US"), returns the base code ("en") for cleaner display.

If multiple dialects are enabled (e.g., "en-US" and "en-GB"), returns the full dialect code ("en-US") to distinguish them.

@spec get_language_info(String.t()) ::
  %{code: String.t(), name: String.t(), flag: String.t()} | nil

Gets language details (name, flag) for a given language code.

Searches in order:

1. Predefined languages (BeamLabCountries) - for full locale details
2. User-configured languages - for custom/less common languages

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

Returns the primary/canonical language for versioning. Uses Settings.get_content_language().

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

Returns the primary language code as it should appear in public URLs.

Content rows keep using the full configured language code (for example "en-GB"), but public routes use the base code ("en").

@spec language_enabled?(String.t(), [String.t()]) :: boolean()

Checks if a language code is enabled, considering base code matching.

Handles cases where:

• The code is en and enabled languages has "en-US" -> matches
• The code is en-US and enabled languages has "en" -> matches

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

Removes base-only language codes when a dialect of the same base is also enabled.

Publishing stores and routes against dialects when they exist. If both "en" and "en-US" are enabled in the broader Languages config, Publishing should treat the bare base code as legacy compatibility data, not as a separate translation target.

@spec order_languages_for_display([String.t()], [String.t()], String.t() | nil) :: [
  String.t()
]

Orders languages for display in the language switcher.

Order: primary language first, then languages with translations (sorted), then languages without translations (sorted).

@spec reserved_language_code?(String.t()) :: boolean()

Checks if a language code is reserved (cannot be used as a slug).

@spec resolve_dialect_for_base(String.t(), [String.t()], keyword()) ::
  String.t() | nil

Finds a language in candidates whose dialect base matches base_code.

Consolidates three near-identical helpers that used to live in Posts, Web.Controller.Language, and StaleFixer — each reimplementing the same "find a dialect for this base code" logic with slightly different tie-breaks and exclusion rules.

Options

• :prefer — when multiple candidates match the base, prefer this specific code if it's among the matches. Useful for primary-language preference; pass LanguageHelpers.get_primary_language() to get the historical "primary wins" tie-break. Note: this option is explicit (not an implicit DB call inside the function) so callers decide when to incur the cached lookup.

• :exclude — code or list of codes to drop from the candidate set before matching. Used by stale-language self-healing to require a TRUE dialect (e.g. exclude "en" when searching for base "en" so the result is always something like "en-US").

Returns the chosen language code, or nil when no candidate matches.

Examples

iex> LanguageHelpers.resolve_dialect_for_base("en", ["en-US", "fr-FR"])
"en-US"

iex> LanguageHelpers.resolve_dialect_for_base("en", ["en", "en-US"], prefer: "en-US")
"en-US"

iex> LanguageHelpers.resolve_dialect_for_base("en", ["en", "en-US"], exclude: "en")
"en-US"

iex> LanguageHelpers.resolve_dialect_for_base("xx", ["en", "fr"])
nil

@spec resolve_language_key(String.t(), [String.t()]) :: String.t()

Resolves a display language code to a key in a language map.

Language maps (e.g., language_titles, language_slugs) use full dialect codes as keys (e.g., "en-US"), but the display/canonical language may be a base code (e.g., "en") when only one dialect is enabled.

Tries exact match first, then falls back to base code matching.

@spec single_language_mode?() :: boolean()

Returns true when the site should behave as single-language for public URLs.

@spec url_language_code(String.t() | nil) :: String.t() | nil

Normalizes a content language code for use in public URLs.

@spec use_language_prefix?(String.t() | nil) :: boolean()

Returns true when public URLs should include a language prefix.

Prefixes are omitted when:

• the site is effectively single-language, or
• the caller requested the default language and the publishing_default_language_no_prefix setting is enabled.