From 0d2d00e437fd267b96bc57c80875e1a399cf763c Mon Sep 17 00:00:00 2001
From: Dominic Rubas <1042243+rubas@users.noreply.github.com>
Date: Sat, 26 Sep 2026 21:24:29 +0200
Subject: [PATCH 1/2] Return an exception struct from put_locale_from_session/2
 for an empty session

The spec and the 1.1.0 changelog say {:error, Exception.t()}, and an
invalid session locale already returns a struct, but a session without
a locale still returned a {module, message} tuple.
---
 lib/localize/plug.ex       | 5 +++--
 test/localize_web_test.exs | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/lib/localize/plug.ex b/lib/localize/plug.ex
index 1d79de8..4ac2973 100644
--- a/lib/localize/plug.ex
+++ b/lib/localize/plug.ex
@@ -29,7 +29,8 @@ defmodule Localize.Plug do
 
   * `{:ok, locale}` or
 
-  * `{:error, {exception, reason}}`
+  * `{:error, exception}`. A session without a locale returns a
+    `Localize.UnknownLocaleError` with a `nil` `:locale_id`.
 
   ### Examples
 
@@ -61,7 +62,7 @@ defmodule Localize.Plug do
   end
 
   def put_locale_from_session(_session, _options) do
-    {:error, {Localize.UnknownLocaleError, "No locale was found in the session"}}
+    {:error, Localize.UnknownLocaleError.exception(locale_id: nil)}
   end
 
   # A locale that Gettext has no translations for is a configuration
diff --git a/test/localize_web_test.exs b/test/localize_web_test.exs
index a63eb0c..c40f507 100644
--- a/test/localize_web_test.exs
+++ b/test/localize_web_test.exs
@@ -51,8 +51,9 @@ defmodule LocalizeWebTest do
     assert Localize.Plug.PutLocale.locale_from_host(nil) == nil
   end
 
-  test "put_locale_from_session returns error when no locale in session" do
-    assert {:error, _} = Localize.Plug.put_locale_from_session(%{})
+  test "put_locale_from_session returns an UnknownLocaleError struct for an empty session" do
+    assert {:error, %Localize.UnknownLocaleError{locale_id: nil}} =
+             Localize.Plug.put_locale_from_session(%{})
   end
 
   test "Phoenix.HTML.Safe protocol for Localize.LanguageTag" do

From 03e01dcc06975045b0e1ae72c78029ba64f4c790 Mon Sep 17 00:00:00 2001
From: Dominic Rubas <1042243+rubas@users.noreply.github.com>
Date: Sat, 26 Sep 2026 21:26:29 +0200
Subject: [PATCH 2/2] Keep the session message with a NoSessionLocaleError

UnknownLocaleError only carries a locale id, so its message for an
empty session was "The locale nil is not known.".
---
 lib/localize/plug.ex       | 12 ++++++++++--
 mix.exs                    |  1 +
 test/localize_web_test.exs |  6 ++++--
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/lib/localize/plug.ex b/lib/localize/plug.ex
index 4ac2973..e4b5689 100644
--- a/lib/localize/plug.ex
+++ b/lib/localize/plug.ex
@@ -8,6 +8,14 @@ defmodule Localize.Plug do
 
   @session_key Localize.Plug.PutLocale.session_key()
 
+  defmodule NoSessionLocaleError do
+    @moduledoc """
+    Returned by `Localize.Plug.put_locale_from_session/2` when the session has no locale.
+    """
+
+    defexception message: "No locale was found in the session"
+  end
+
   @doc """
   Puts the locale from the session into the current process.
 
@@ -30,7 +38,7 @@ defmodule Localize.Plug do
   * `{:ok, locale}` or
 
   * `{:error, exception}`. A session without a locale returns a
-    `Localize.UnknownLocaleError` with a `nil` `:locale_id`.
+    `Localize.Plug.NoSessionLocaleError`.
 
   ### Examples
 
@@ -62,7 +70,7 @@ defmodule Localize.Plug do
   end
 
   def put_locale_from_session(_session, _options) do
-    {:error, Localize.UnknownLocaleError.exception(locale_id: nil)}
+    {:error, %NoSessionLocaleError{}}
   end
 
   # A locale that Gettext has no translations for is a configuration
diff --git a/mix.exs b/mix.exs
index d6854b1..e09cfc9 100644
--- a/mix.exs
+++ b/mix.exs
@@ -76,6 +76,7 @@ defmodule LocalizeWeb.MixProject do
       groups_for_modules: [
         Plugs: [
           Localize.Plug,
+          Localize.Plug.NoSessionLocaleError,
           Localize.Plug.PutLocale,
           Localize.Plug.PutSession,
           Localize.Plug.AcceptLanguage,
diff --git a/test/localize_web_test.exs b/test/localize_web_test.exs
index c40f507..0e3e5af 100644
--- a/test/localize_web_test.exs
+++ b/test/localize_web_test.exs
@@ -51,9 +51,11 @@ defmodule LocalizeWebTest do
     assert Localize.Plug.PutLocale.locale_from_host(nil) == nil
   end
 
-  test "put_locale_from_session returns an UnknownLocaleError struct for an empty session" do
-    assert {:error, %Localize.UnknownLocaleError{locale_id: nil}} =
+  test "put_locale_from_session returns a NoSessionLocaleError for an empty session" do
+    assert {:error, %Localize.Plug.NoSessionLocaleError{} = error} =
              Localize.Plug.put_locale_from_session(%{})
+
+    assert Exception.message(error) == "No locale was found in the session"
   end
 
   test "Phoenix.HTML.Safe protocol for Localize.LanguageTag" do