Release 1.0.0: add credo and strict dialyzer, fix HTML select and options specs

Author: kipcole9

CHANGELOG.md

@@ -2,11 +2,19 @@
 
 All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0-rc.0] — 2026-07-30
+## [1.0.0] — 2026-07-31
+
+The first stable release, built on Localize 1.0.
 
 ### Changes
 
-* Updated `Localize` to `"~> 1.0-rc"`.
+* Requires `localize ~> 1.0`.
+
+### Fixed
+
+* `Localize.HTML.Unit.select/3` is specified as returning `{:error, Exception.t()}`. Localize 1.0 reports an invalid unit or locale as an exception struct rather than a `{module, message}` tuple, so the previous specification did not describe what the function returns.
+
+* `currency_options/1`, `locale_options/1`, `territory_options/1` and `unit_options/1` no longer claim to return an error tuple. They validate by raising, so the documented error return could not occur.
 
 ## [0.8.0] — 2026-06-25
 

README.md

@@ -27,7 +27,7 @@ Add `localize_web` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:localize_web, "~> 0.1.0"}
+    {:localize_web, "~> 1.0"}
   ]
 end
 ```

lib/localize/html/currency.ex

@@ -45,8 +45,6 @@ defmodule Localize.HTML.Currency do
 
   * A `t:Phoenix.HTML.safe/0` select tag, or
 
-  * `{:error, {module(), binary()}}` if validation fails.
-
   ### Examples
 
       iex> Localize.HTML.Currency.select(:my_form, :currency, selected: :USD)
@@ -79,12 +77,10 @@ defmodule Localize.HTML.Currency do
 
   ### Returns
 
-  * A list of `{display_name, currency_code}` tuples, or
-
-  * `{:error, {module(), binary()}}` if validation fails.
+  * A list of `{display_name, currency_code}` tuples.
 
   """
-  @spec currency_options(select_options) :: list(tuple()) | {:error, {module(), binary()}}
+  @spec currency_options(select_options) :: list(tuple())
 
   def currency_options(options \\ [])
 

lib/localize/html/locale.ex

@@ -56,8 +56,6 @@ defmodule Localize.HTML.Locale do
 
   * A `t:Phoenix.HTML.safe/0` select tag, or
 
-  * `{:error, {module(), binary()}}` if validation fails.
-
   ### Examples
 
       iex> Localize.HTML.Locale.select(:my_form, :locale_list, selected: "en")
@@ -89,12 +87,10 @@ defmodule Localize.HTML.Locale do
 
   ### Returns
 
-  * A list of `{display_name, locale_string}` tuples, or
-
-  * `{:error, {module(), binary()}}` if validation fails.
+  * A list of `{display_name, locale_string}` tuples.
 
   """
-  @spec locale_options(select_options) :: list(tuple()) | {:error, {module(), binary()}}
+  @spec locale_options(select_options) :: list(tuple())
 
   def locale_options(options \\ [])
 

lib/localize/html/territory.ex

@@ -58,8 +58,6 @@ defmodule Localize.HTML.Territory do
 
   * A `t:Phoenix.HTML.safe/0` select tag, or
 
-  * `{:error, {module(), binary()}}` if validation fails.
-
   ### Examples
 
       iex> Localize.HTML.Territory.select(:my_form, :territory, selected: :AU)
@@ -92,12 +90,10 @@ defmodule Localize.HTML.Territory do
 
   ### Returns
 
-  * A list of `{display_name, territory_code}` tuples, or
-
-  * `{:error, {module(), binary()}}` if validation fails.
+  * A list of `{display_name, territory_code}` tuples.
 
   """
-  @spec territory_options(select_options) :: list(tuple()) | {:error, {module(), binary()}}
+  @spec territory_options(select_options) :: list(tuple())
 
   def territory_options(options \\ [])
 
@@ -221,16 +217,21 @@ defmodule Localize.HTML.Territory do
   end
 
   defp name_from_territory(territory, options) do
-    with {:ok, name} <- Localize.Territory.display_name(territory, options) do
-      name
-    else
-      {:error, _} ->
-        default_options = Keyword.delete(options, :style)
+    case Localize.Territory.display_name(territory, options) do
+      {:ok, name} -> name
+      {:error, _reason} -> name_from_default_style(territory, options)
+    end
+  end
+
+  # Not every territory has a name in every style, so a failed lookup
+  # retries with the locale's default style before falling back to the
+  # territory code itself.
+  defp name_from_default_style(territory, options) do
+    default_options = Keyword.delete(options, :style)
 
-        case Localize.Territory.display_name(territory, default_options) do
-          {:ok, name} -> name
-          _ -> to_string(territory)
-        end
+    case Localize.Territory.display_name(territory, default_options) do
+      {:ok, name} -> name
+      _error -> to_string(territory)
     end
   end
 

lib/localize/html/unit.ex

@@ -48,8 +48,6 @@ defmodule Localize.HTML.Unit do
 
   * A `t:Phoenix.HTML.safe/0` select tag, or
 
-  * `{:error, {module(), binary()}}` if validation fails.
-
   ### Examples
 
       iex> Localize.HTML.Unit.select(:my_form, :unit, selected: :foot)
@@ -61,7 +59,7 @@ defmodule Localize.HTML.Unit do
           select_options
         ) ::
           Phoenix.HTML.safe()
-          | {:error, {module(), binary()}}
+          | {:error, Exception.t()}
 
   def select(form, field, options \\ [])
 
@@ -82,12 +80,10 @@ defmodule Localize.HTML.Unit do
 
   ### Returns
 
-  * A list of `{display_name, unit_code}` tuples, or
-
-  * `{:error, {module(), binary()}}` if validation fails.
+  * A list of `{display_name, unit_code}` tuples.
 
   """
-  @spec unit_options(select_options) :: list(tuple()) | {:error, {module(), binary()}}
+  @spec unit_options(select_options) :: list(tuple())
 
   def unit_options(options \\ [])
 

lib/localize/plug.ex

@@ -54,22 +54,7 @@ defmodule Localize.Plug do
 
     with {:ok, locale} <- Localize.validate_locale(locale) do
       Localize.put_locale(locale)
-
-      Enum.each(gettext_backends, fn gettext_backend ->
-        case Localize.Locale.gettext_locale_id(locale, gettext_backend) do
-          {:ok, gettext_locale} ->
-            Gettext.put_locale(gettext_backend, gettext_locale)
-
-          {:error, _reason} ->
-            require Logger
-
-            Logger.warning(
-              "Localize.Plug.put_locale_from_session/2: locale #{inspect(locale.cldr_locale_id)} " <>
-                "does not have a matching Gettext locale for backend #{inspect(gettext_backend)}. " <>
-                "No Gettext locale has been set."
-            )
-        end
-      end)
+      Enum.each(gettext_backends, &put_gettext_locale(&1, locale))
 
       {:ok, locale}
     end
@@ -79,6 +64,25 @@ defmodule Localize.Plug do
     {:error, {Localize.UnknownLocaleError, "No locale was found in the session"}}
   end
 
+  # A locale that Gettext has no translations for is a configuration
+  # mismatch rather than an error: the locale is still set for Localize,
+  # and only the Gettext locale is left alone.
+  defp put_gettext_locale(gettext_backend, locale) do
+    case Localize.Locale.gettext_locale_id(locale, gettext_backend) do
+      {:ok, gettext_locale} ->
+        Gettext.put_locale(gettext_backend, gettext_locale)
+
+      {:error, _reason} ->
+        require Logger
+
+        Logger.warning(
+          "Localize.Plug.put_locale_from_session/2: locale #{inspect(locale.cldr_locale_id)} " <>
+            "does not have a matching Gettext locale for backend #{inspect(gettext_backend)}. " <>
+            "No Gettext locale has been set."
+        )
+    end
+  end
+
   defp normalize_gettext_backends(nil), do: []
   defp normalize_gettext_backends(backend) when is_atom(backend), do: [backend]
   defp normalize_gettext_backends(backends) when is_list(backends), do: backends

lib/localize/plug/put_locale.ex

@@ -89,7 +89,9 @@ defmodule Localize.Plug.PutLocale do
 
   @doc false
   def call(conn, options) do
-    if locale = locale_from_params(conn, options[:from], options) || default(conn, options) do
+    locale = locale_from_params(conn, options[:from], options) || default(conn, options)
+
+    if locale do
       Localize.put_locale(locale)
 
       Enum.each(options[:gettext], fn gettext_backend ->

lib/localize/plug/put_session.ex

@@ -44,7 +44,7 @@ defmodule Localize.Plug.PutSession do
                 "Invalid option for `:as`. Valid settings are :string or :language_tag. Found #{inspect(other)}"
       end
 
-    if length(options) > 0,
+    if options != [],
       do:
         raise(ArgumentError, "Invalid options. Valid option is `:as`. Found #{inspect(options)}")
 

lib/localize/routes.ex

@@ -102,10 +102,15 @@ defmodule Localize.Routes do
       Localize.Routes.delete_original_path(routes)
     )
 
+    # `Phoenix.Router.Route.exprs/1` gained a second argument in later
+    # Phoenix releases. `apply/3` is what lets one build support both
+    # arities — a direct call to the absent one would not compile.
     routes_with_exprs =
       if function_exported?(Phoenix.Router.Route, :exprs, 2) do
+        # credo:disable-for-next-line Credo.Check.Refactor.Apply
         Enum.map(routes, &{&1, apply(Phoenix.Router.Route, :exprs, [&1, forwards])})
       else
+        # credo:disable-for-next-line Credo.Check.Refactor.Apply
         Enum.map(routes, &{&1, apply(Phoenix.Router.Route, :exprs, [&1])})
       end
 
@@ -202,24 +207,8 @@ defmodule Localize.Routes do
   defmacro localize(locale_ids, do: route) when is_list(locale_ids) do
     gettext_backend = Module.get_attribute(__CALLER__.module, :_gettext_backend)
 
-    for locale_id <- locale_ids do
-      with {:ok, locale} <- Localize.validate_locale(locale_id) do
-        case Localize.Locale.gettext_locale_id(locale, gettext_backend) do
-          {:ok, gettext_locale} ->
-            quote do
-              localize(
-                {unquote(Macro.escape(locale)), unquote(gettext_locale)},
-                unquote(route)
-              )
-            end
-
-          {:error, _reason} ->
-            warn_no_gettext_locale(locale_id, route)
-        end
-      else
-        {:error, %{__exception__: true} = exception} -> raise exception
-      end
-    end
+    locale_ids
+    |> Enum.map(&localized_route(&1, route, gettext_backend))
     |> Enum.reject(&is_nil/1)
     |> Enum.uniq_by(&canonical_route/1)
   end
@@ -281,6 +270,32 @@ defmodule Localize.Routes do
           """
   end
 
+  # Expands one locale into a `localize/2` call carrying both the
+  # resolved language tag and its Gettext locale. A locale with no
+  # Gettext translations is warned about and skipped; an invalid locale
+  # identifier is a mistake in the router and raises.
+  defp localized_route(locale_id, route, gettext_backend) do
+    case Localize.validate_locale(locale_id) do
+      {:ok, locale} -> gettext_localized_route(locale, locale_id, route, gettext_backend)
+      {:error, exception} -> raise exception
+    end
+  end
+
+  defp gettext_localized_route(locale, locale_id, route, gettext_backend) do
+    case Localize.Locale.gettext_locale_id(locale, gettext_backend) do
+      {:ok, gettext_locale} ->
+        quote do
+          localize(
+            {unquote(Macro.escape(locale)), unquote(gettext_locale)},
+            unquote(route)
+          )
+        end
+
+      {:error, _reason} ->
+        warn_no_gettext_locale(locale_id, route)
+    end
+  end
+
   defp do_localize(field, {locale, gettext_locale}, gettext_backend, {verb, meta, [path | args]}) do
     locale = eval_locale(locale)