Add new function put_locale!/2 (#420)

* enhance documentation for put_locale/2

* add new function put_locale!/2

Author: abdelhalim97

lib/gettext.ex

@@ -763,6 +763,19 @@ defmodule Gettext do
       Gettext.get_locale(MyApp.Gettext)
       #=> "pt_BR"
 
+  The current process's locale will change even if the passed `locale` is not
+  supported. If you think this can cause an issue consider using `known_locales/1`
+  to handle unsupported locales.
+
+  ## Example
+
+      # Handle unsupported locales based on your requirements
+      defp handle_locale(locale, true, backend), do: {:ok, Process.put(backend, locale)}
+      defp handle_locale(_locale, false, backend), do: {:error, :unsupported_locale}
+
+      # In your main function
+      is_in_allowed_locale = locale in known_locales(backend)
+      handle_locale(locale, is_in_allowed_locale, backend)
   """
   @doc section: :locale
   @spec put_locale(backend, locale) :: locale | nil
@@ -771,6 +784,17 @@ defmodule Gettext do
   def put_locale(_backend, locale),
     do: raise(ArgumentError, "put_locale/2 only accepts binary locales, got: #{inspect(locale)}")
 
+  @doc """
+  Similar to `put_locale/2`, but it raises an error if the passed locale doesn't exist in the known_locales.
+  """
+  @doc section: :locale
+  @spec put_locale!(backend, locale) :: locale | nil
+  def put_locale!(backend, locale) when is_binary(locale),
+    do: put_locale_with_fallback(backend, locale)
+
+  def put_locale!(_backend, locale),
+    do: raise(ArgumentError, "put_locale/2 only accepts binary locales, got: #{inspect(locale)}")
+
   @doc """
   Returns the message of the given string with a given context in the given domain.
 
@@ -1154,4 +1178,18 @@ defmodule Gettext do
 
   defp domain_or_default(backend, :default), do: backend.__gettext__(:default_domain)
   defp domain_or_default(_backend, domain) when is_binary(domain), do: domain
+
+  @spec put_locale_with_fallback(backend, locale) :: binary() | nil
+  defp put_locale_with_fallback(backend, locale) do
+    allowed_locales = known_locales(backend)
+    is_allowed_locale = locale in allowed_locales
+
+    case is_allowed_locale do
+      true ->
+        put_locale(backend, locale)
+
+      false ->
+        raise(ArgumentError, "put_locale!/2 only support known locales, got: #{inspect(locale)}")
+    end
+  end
 end

test/gettext_test.exs

@@ -78,6 +78,17 @@ defmodule GettextTest do
     end
   end
 
+  describe "put_locale!/2" do
+    test "raises an error when unsupported locale is passed as argument" do
+      msg = "put_locale!/2 only support known locales, got: \"kr\""
+      assert Gettext.known_locales(Backend) == ["it", "ja"]
+
+      assert_raise ArgumentError, msg, fn ->
+        Gettext.put_locale!(Backend, "kr")
+      end
+    end
+  end
+
   describe "with_locale/3" do
     test "doesn't raise if no locale was set (defaulting to 'en')" do
       Process.delete(Backend)