82 lines
3.0 KiB
Elixir
82 lines
3.0 KiB
Elixir
defmodule BDS.Desktop.UILocale do
|
|
@moduledoc """
|
|
Per-render UI locale binding for the desktop LiveView shell.
|
|
|
|
The shell renders the UI in the user's selected language, which can differ
|
|
from the OS locale and from the project's `mainLanguage`. Phoenix HEEx
|
|
templates call `translated/1,2` helpers without an explicit locale, so we
|
|
bind the active locale once per `render/1` and the helpers read it back.
|
|
|
|
This module encapsulates that binding so call sites do not touch the raw
|
|
process dictionary directly. Use `with_locale/2` around any render or
|
|
component that needs a locale binding; use `current/0` to read it.
|
|
|
|
## Invariant
|
|
|
|
Every code path that evaluates HEEx templates containing `translated/1,2`
|
|
calls **must** call `UILocale.put/1` before template evaluation:
|
|
|
|
* `ShellLive.render/1` — sets locale at the top of every LiveView render.
|
|
* `SidebarComponents.sidebar_content/1` — sets locale before the function
|
|
component's HEEx (runs in the same process, may be called outside
|
|
the parent render cycle via `send_update`).
|
|
* `MenuBar.mount/1` and `MenuBar.handle_info({:set_ui_locale, _})` — set
|
|
locale in the separate menu-bar process which has its own render cycle.
|
|
|
|
Violating this invariant causes `current/0` to return a stale or `nil`
|
|
locale, producing untranslated UI text.
|
|
|
|
Direct use of `Process.put(:bds_ui_locale, _)` or
|
|
`Process.get(:bds_ui_locale)` is forbidden outside this module.
|
|
"""
|
|
|
|
@key :bds_ui_locale
|
|
|
|
@typedoc "A normalized UI locale code such as `\"en\"` or `\"de\"`."
|
|
@type locale :: String.t() | nil
|
|
|
|
@doc """
|
|
Bind `locale` for any subsequent reads of `current/0` in this process.
|
|
|
|
Used at LiveView render boundaries. The binding persists past the call
|
|
(mirroring per-process locale state) so that lazily evaluated child
|
|
components see the active locale. Each render boundary overwrites it.
|
|
"""
|
|
@spec put(locale()) :: :ok
|
|
def put(locale) do
|
|
Process.put(@key, locale)
|
|
BDS.Gettext.put_locale(locale)
|
|
:ok
|
|
end
|
|
|
|
@doc """
|
|
Set the UI locale for the duration of `fun`, then restore the prior value.
|
|
|
|
Safe under exceptions: the prior binding is restored in an `after` clause.
|
|
Use this for short-lived non-LiveView contexts (background tasks, scripts)
|
|
where eager evaluation guarantees the binding is consumed before `fun`
|
|
returns. Do not use around LiveView `render/1` because the returned
|
|
`Phoenix.LiveView.Rendered` struct evaluates its dynamic parts lazily.
|
|
"""
|
|
@spec with_locale(locale(), (-> result)) :: result when result: var
|
|
def with_locale(locale, fun) when is_function(fun, 0) do
|
|
previous = Process.get(@key)
|
|
Process.put(@key, locale)
|
|
|
|
try do
|
|
fun.()
|
|
after
|
|
restore(previous)
|
|
end
|
|
end
|
|
|
|
@doc """
|
|
Read the active UI locale binding for this process, or `nil` when unset.
|
|
"""
|
|
@spec current() :: locale()
|
|
def current, do: Process.get(@key)
|
|
|
|
defp restore(nil), do: Process.delete(@key)
|
|
defp restore(value), do: Process.put(@key, value)
|
|
end
|