Localize.PhoenixRuntime (localize_phoenix_runtime v0.1.0-alpha.1)

View Source

This module provides:

  • A Plug (plug/3) to update the connection with locale attributes and store them in the session.
  • A LiveView lifecycle hook (handle_params/4) to update the socket with locale attributes.

Both are optimized for performance.

Locale values can be sourced independently from locations like:

  • Pre-compiled route attributes
  • The Accept-Language header sent by the client (fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7)
  • Query parameters (?lang=fr)
  • Hostname (fr.example.com)
  • Path parameters (/fr/products)
  • Assigns (assign(socket, [locale: "fr"]))
  • Body parameters
  • Stored cookie
  • Session data

Runtime detection is configured by specifying sources for locale attributes (:locale, :language, :region).

Locale Attributes and Their Sources

Each attribute (:locale, :language, :region) can have its own list of sources and parameter names, where the parameter name is the key to get from the source. The parameter should be provided as a string.

Supported Sources
  • :accept_language: From the header sent by the client (e.g. fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7)
  • :assigns: From conn and socket assigns.
  • :attrs: From precompiled route attributes.
  • :body: From request body parameters.
  • :cookie: From request cookies.
  • :host: From the hostname (e.g., en.example.com).
  • :path: From path parameters (e.g., /:lang/users).
  • :query: From query parameters (e.g., ?locale=de).
  • :session: From session data.
Default Configuration

The default sources for each attribute are: [:query, :session, :cookie, :accept_language, :path, :attrs].

Overriding Detection Behavior

You can customize sources and parameters per attribute:

Examples:

# In your config module
locale_sources: [:query, :session, :accept_language], # Order matters
locale_params: ["locale"], # Look for ?locale=... etc

language_sources: [:path, :host],
language_params: ["lang"], # Look for /:lang/... etc

region_sources: [:attrs] # Only use region from extra provided attributes
# region_params defaults to ["region"]

Summary

Functions

Plug callback to detect and assign locale attributes to the connection.

Types

conn()

@type conn() :: Plug.Conn.t()

params()

@type params() :: %{optional(String.t()) => any()}

plug_opts()

@type plug_opts() :: keyword()

socket()

@type socket() :: Phoenix.LiveView.Socket.t()

url()

@type url() :: String.t()

Functions

call(conn, plug_opts, extra_attrs \\ %{})

@spec call(conn(), plug_opts(), extra_attrs :: Localize.PhoenixRuntime.Types.attrs()) ::
  conn()

Plug callback to detect and assign locale attributes to the connection.

Examines configured sources (params, session, headers, etc.), updates conn.assigns, merges attributes into conn.private.loc, and persists relevant attributes in the session.

handle_params(params, url, socket, extra_attrs \\ %{})

@spec handle_params(
  params(),
  url(),
  socket(),
  extra_attrs :: Localize.PhoenixRuntime.Types.attrs()
) ::
  {:cont, socket()}

LiveView handle_params/4 callback hook.

Detects locale settings based on URL, params, and socket state, then updates the socket assigns and Localize attributes.