@spec available_languages(struct(), atom()) :: [String.t()]

Gets all languages that have a value for a field.

Examples

iex> Translations.available_languages(product, :title)
["en", "ru"]

@spec category_fields() :: [atom()]

Returns the list of translatable fields for categories.

@spec changeset_attrs(struct(), atom(), String.t(), any()) :: map()

Builds changeset attrs for localized field update.

Merges the new value into the existing field map for the given language.

Examples

iex> Translations.changeset_attrs(product, :title, "ru", "Новое кашпо")
%{title: %{"en" => "Planter", "ru" => "Новое кашпо"}}

@spec changeset_attrs_multi(struct(), String.t(), map()) :: map()

Builds changeset attrs for multiple localized fields at once.

Examples

iex> Translations.changeset_attrs_multi(product, "ru", %{title: "Кашпо", slug: "kashpo"})
%{title: %{"en" => "Planter", "ru" => "Кашпо"}, slug: %{"en" => "planter", "ru" => "kashpo"}}

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

Returns the default/master language code.

Checks Languages module first, falls back to Settings content language, then defaults to "en".

Examples

iex> Translations.default_language()
"en"

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

Returns list of enabled language codes.

When Languages module is enabled, returns all enabled language codes. Otherwise returns only the default language.

Examples

iex> Translations.enabled_languages()
["en", "es", "ru"]

# When Languages module disabled:
iex> Translations.enabled_languages()
["en"]

@spec get(struct(), atom(), String.t()) :: any()

Gets a localized value with automatic fallback chain.

Fallback order:

1. Exact language match
2. Default language
3. First available value

Parameters

• entity - Product or Category struct
• field - Field atom (e.g., :title, :name, :slug)
• language - Language code (e.g., "ru", "en")

Examples

iex> product = %Product{title: %{"en" => "Planter", "ru" => "Кашпо"}}
iex> Translations.get(product, :title, "ru")
"Кашпо"

iex> Translations.get(product, :title, "fr")
"Planter"  # Falls back to default or first available

@spec get_all_for_language(struct(), String.t(), [atom()]) :: map()

Gets all values for a specific language from the entity's localized fields.

Returns a map of field => value for the given language.

Examples

iex> Translations.get_all_for_language(product, "ru", [:title, :slug, :description])
%{title: "Кашпо", slug: "kashpo", description: "Описание"}

@spec get_display(struct(), atom(), String.t(), keyword()) :: any()

Storefront-only wrapper around get/3: runs the resolved value through PhoenixKitEcommerce.NamePrefix.strip/1, which hides a shop-configured vocabulary prefix ("3D Printed Costume Masks" -> "Costume Masks") when the shop_name_prefixes setting names one — a no-op by default.

Call this ONLY for a display field on a genuine public storefront page (:title on a product, :name on a category), reading a real %Product{}/%Category{} struct. Never call it for :slug — slugs are URLs and must never be rewritten — and never from an admin surface or the Shopify sync path: an operator editing a category must see what is actually stored, and the sync must compare and write the raw Shopify-sourced value.

A cart line, order line item, or invoice's stored product_title/ "name" is a DIFFERENT kind of value — a snapshot taken at add-to-cart time, not a live read of the product — and is never touched by this function at all (it isn't a %Product{}/%Category{} field access in the first place). The snapshot itself stays exactly as stored, same as a snapshotted price; but DISPLAYING it on a storefront page (the cart, checkout, and order-confirmation pages, and the customer's own order history) still applies the prefix, by calling PhoenixKitEcommerce.NamePrefix.strip/1 directly on the snapshot string — the shopper is not shopping from a stored record, so there is no earlier "what they actually saw" to preserve; they are looking at the same storefront naming as every other page. Only a persisted WRITE, and any value compared against or sent to Shopify, must stay raw.

Options

• :prefixes — a precomputed NamePrefix.prefixes/0 list. Every call without it reads the setting through core's settings cache (a process round-trip), so a template rendering a LIST of products or categories resolves the list once and passes it to every get_display/4 call inside the loop.

Examples

iex> Translations.get_display(category, :name, "en")
"Costume Masks"

iex> prefixes = NamePrefix.prefixes()
iex> Translations.get_display(category, :name, "en", prefixes: prefixes)
"Costume Masks"

@spec get_field(struct(), atom(), String.t()) :: any()

DEPRECATED: Use get/3 instead.

This function exists for backward compatibility during migration.

@spec get_slug(struct(), String.t()) :: String.t() | nil

Gets the localized slug with fallback.

Convenience function for URL slug retrieval.

Examples

iex> Translations.get_slug(product, "es")
"maceta-geometrica"

@spec has_translation?(struct(), atom(), String.t()) :: boolean()

Checks if translation exists for language in a specific field.

Examples

iex> Translations.has_translation?(product, :title, "ru")
true

iex> Translations.has_translation?(product, :title, "zh")
false

@spec languages_enabled?() :: boolean()

Checks if Languages module is enabled.

@spec product_fields() :: [atom()]

Returns the list of translatable fields for products.

@spec put(struct(), atom(), String.t(), any()) :: struct()

Sets a localized value for a language.

Returns the updated entity struct (not persisted to database).

Examples

iex> product = Translations.put(product, :title, "ru", "Новое кашпо")
%Product{title: %{"en" => "Planter", "ru" => "Новое кашпо"}}

@spec put_all(struct(), String.t(), map()) :: struct()

Sets multiple translated fields for a language.

Returns the updated entity struct (not persisted to database).

Examples

iex> product = Translations.put_all(product, "es", %{title: "Maceta", slug: "maceta"})
%Product{title: %{"en" => "Planter", "es" => "Maceta"}, ...}

@spec put_field(struct(), atom(), String.t(), any()) :: struct()

DEPRECATED: Use put/4 instead.

This function exists for backward compatibility during migration.

@spec translatable_fields(struct()) :: [atom()]

Returns translatable fields based on entity type.

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

DEPRECATED: Use changeset_attrs_multi/3 instead.

Builds changeset attrs for updating translations. This function adapts the old API to the new localized fields approach.

@spec translation_status(struct(), String.t(), [atom()] | nil) :: map()

Gets translation completeness for a language across all translatable fields.

Examples

iex> Translations.translation_status(product, "ru")
%{complete: 4, total: 6, percentage: 67, missing: [:body_html, :seo_description]}