Add path_for/2 and url_for/2 to Localize.VerifiedRoutes

Author: kipcole9

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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).
 
+## [0.6.0] - 2026-05-11
+
+### Enhancements
+
+* Add `path_for/2` and `url_for/2` macros to `Localize.VerifiedRoutes` to render a verified path or URL in an explicit locale without changing the process-wide locale, supporting language-switcher and hreflang use cases that need every configured locale rendered in one template pass.
+
 ## [0.5.1] - 2026-04-25
 
 ### Bug Fixes

guides/phoenix-localized-routing.md

@@ -257,6 +257,41 @@ The `~q` sigil supports the same locale interpolations as the `localize` macro:
 # Produces "/fr/pages_fr/intro" when the locale is :fr
 ```
 
+### Rendering a Path or URL in a Specific Locale
+
+`~q` dispatches on the *current* process locale (`Localize.get_locale/0`). When you need to render a link in a different locale at the call site — without changing the process locale — use `path_for/2` and `url_for/2`. Typical use cases are language switchers and emitting hreflang links per locale in one template pass.
+
+```elixir
+<.link navigate={path_for(:fr, "/users")}>Français</.link>
+<.link navigate={path_for(:de, "/users")}>Deutsch</.link>
+```
+
+The locale argument can also be a runtime expression, which is the more common form when the locale list is iterated:
+
+```elixir
+<%= for locale <- [:en, :fr, :de] do %>
+  <.link navigate={path_for(locale, "/users")}><%= locale %></.link>
+<% end %>
+```
+
+`url_for/2` returns a full URL via `Phoenix.VerifiedRoutes.url/1`:
+
+```elixir
+url_for(:fr, "/users")
+#=> "http://localhost:4000/users_fr"
+```
+
+The route argument accepts the same form as `~q` — a string literal with optional `#{...}` interpolations and `:locale` / `:language` / `:territory` substitutions.
+
+For ad-hoc blocks where you need a whole region of code to run under a specific locale (perhaps because you also want locale-sensitive number or date formatting), `Localize.with_locale/2` temporarily switches the locale and restores it afterwards:
+
+```elixir
+Localize.with_locale(:fr, fn -> ~q"/users" end)
+#=> "/users_fr"
+```
+
+Use `path_for/2` for single-call locale forcing; use `Localize.with_locale/2` for whole-block temporary locale changes.
+
 ## Inspecting Localized Routes
 
 Localized routes are stored in a `LocalizedRoutes` submodule. You can inspect them with the `phx.routes` mix task:

lib/localize/routes/verified_routes.ex

@@ -28,6 +28,25 @@ defmodule Localize.VerifiedRoutes do
 
   * `:territory` is replaced with the CLDR territory code.
 
+  ### Rendering a path or URL in a specific locale
+
+  `sigil_q` dispatches on the *current* process locale set by
+  `Localize.put_locale/1`. When you need to render a link in a different
+  locale without changing the process locale — for example, emitting a
+  language switcher that lists the same page in every configured locale —
+  use `path_for/2` and `url_for/2`:
+
+      # In a template, with @locale bound from the request or session:
+      <.link href={path_for(@locale, "/users")}>Users</.link>
+
+      # Render every configured locale in one pass (language switcher):
+      for locale <- [:en, :fr, :de] do
+        path_for(locale, "/users")
+      end
+
+      url_for(:fr, "/users")
+      #=> "http://localhost/users_fr"
+
   """
 
   defmacro __using__(opts) do
@@ -123,6 +142,96 @@ defmodule Localize.VerifiedRoutes do
     end
   end
 
+  @doc ~S'''
+  Generates a localized verified path in a specific locale.
+
+  Unlike `sigil_q/2`, which dispatches on the *current* locale
+  (`Localize.get_locale/0`), `path_for/2` lets the caller force a particular
+  locale at the call site without changing the process-wide locale. This is
+  useful when rendering links in multiple locales within a single template
+  (for example, a language switcher).
+
+  ### Arguments
+
+  * `locale` is any locale id configured in the gettext backend. May be a
+    literal atom or a runtime expression.
+
+  * `route` is a string literal route (with optional `#{...}` interpolations),
+    as accepted by `sigil_q/2`.
+
+  ### Examples
+
+      path_for(:fr, "/users")
+      #=> "/utilisateurs"
+
+      for locale <- [:en, :fr] do
+        {locale, path_for(locale, "/users")}
+      end
+      #=> [en: "/users", fr: "/utilisateurs"]
+
+  '''
+  defmacro path_for(locale, route) do
+    gettext = Module.get_attribute(__CALLER__.module, :_localize_gettext_backend)
+    locale_ids = Localize.Routes.locales_from_gettext(gettext)
+    route_ast = Localize.VerifiedRoutes.normalize_route_ast(route)
+
+    case_clauses =
+      Localize.VerifiedRoutes.sigil_q_case_clauses(route_ast, [], locale_ids, gettext)
+
+    quote location: :keep do
+      case unquote(locale) do
+        unquote(case_clauses)
+      end
+    end
+  end
+
+  @doc ~S'''
+  Generates a localized verified URL in a specific locale.
+
+  Like `path_for/2` but returns a full URL via `Phoenix.VerifiedRoutes.url/1`.
+
+  ### Arguments
+
+  * `locale` is any locale id configured in the gettext backend.
+
+  * `route` is a string literal route accepted by `sigil_q/2`.
+
+  '''
+  defmacro url_for(locale, route) do
+    gettext = Module.get_attribute(__CALLER__.module, :_localize_gettext_backend)
+    locale_ids = Localize.Routes.locales_from_gettext(gettext)
+    route_ast = Localize.VerifiedRoutes.normalize_route_ast(route)
+
+    case_clauses =
+      Localize.VerifiedRoutes.sigil_q_case_clauses(route_ast, [], locale_ids, gettext)
+
+    case_expr =
+      quote location: :keep do
+        case unquote(locale) do
+          unquote(case_clauses)
+        end
+      end
+
+    wrap_sigil_p_in_url(case_expr)
+  end
+
+  @doc false
+  # Normalises the second arg of `path_for/2`/`url_for/2`. Accepts either a
+  # plain string literal (passed straight through the macro as a binary) or
+  # an interpolated-string AST (`{:<<>>, _, _}`) and returns the AST shape
+  # expected by `sigil_q_case_clauses/4`.
+  def normalize_route_ast(route) when is_binary(route) do
+    {:<<>>, [], [route]}
+  end
+
+  def normalize_route_ast({:<<>>, _, _} = ast), do: ast
+
+  def normalize_route_ast(other) do
+    raise ArgumentError,
+          "path_for/2 and url_for/2 expect a string literal route " <>
+            "(optionally with \#{...} interpolations); got: #{Macro.to_string(other)}"
+  end
+
   @doc false
   def sigil_q_case_clauses(route, flags, locale_ids, gettext_backend) do
     for locale_id <- locale_ids do

mix.exs

@@ -1,7 +1,7 @@
 defmodule LocalizeWeb.MixProject do
   use Mix.Project
 
-  @version "0.5.1"
+  @version "0.6.0"
 
   def project do
     [

test/path_for_test.exs

@@ -0,0 +1,77 @@
+defmodule PathFor.Test do
+  use ExUnit.Case
+
+  use Localize.VerifiedRoutes,
+    router: MyApp.Router,
+    endpoint: MyApp.Endpoint,
+    gettext: MyApp.Gettext
+
+  # `path_for/2` and `url_for/2` let the caller force a specific locale at the
+  # call site, independent of the process-wide locale set by
+  # `Localize.put_locale/1`. Mirrors the macros added to ex_cldr_routes for
+  # https://github.com/elixir-cldr/cldr_routes/issues/18.
+
+  describe "path_for/2" do
+    test "renders the literal locale's translation regardless of current locale" do
+      Localize.put_locale(:en)
+      assert path_for(:fr, "/users") == "/users_fr"
+      assert path_for(:de, "/users") == "/users_de"
+      assert path_for(:en, "/users") == "/users"
+    end
+
+    test "does not mutate the process locale" do
+      Localize.put_locale(:en)
+      _ = path_for(:fr, "/users")
+      assert Localize.get_locale().cldr_locale_id == :en
+    end
+
+    test "supports a runtime locale expression" do
+      Localize.put_locale(:en)
+
+      for locale <- [:en, :fr, :de] do
+        expected =
+          case locale do
+            :en -> "/users"
+            :fr -> "/users_fr"
+            :de -> "/users_de"
+          end
+
+        assert path_for(locale, "/users") == expected
+      end
+    end
+
+    test "supports interpolation in the route string" do
+      user_id = 42
+      assert path_for(:fr, "/users/#{user_id}") == "/users_fr/42"
+    end
+
+    test "supports :locale / :language / :territory interpolation" do
+      assert path_for(:de, "/users/:locale") == "/users_de/de"
+      assert path_for(:fr, "/users/:territory") == "/users_fr/fr"
+    end
+
+    test "renders multiple locales in one template-style pass" do
+      Localize.put_locale(:en)
+
+      pairs =
+        for locale <- [:en, :fr, :de] do
+          {locale, path_for(locale, "/users")}
+        end
+
+      assert pairs == [{:en, "/users"}, {:fr, "/users_fr"}, {:de, "/users_de"}]
+    end
+  end
+
+  describe "url_for/2" do
+    test "renders a full URL in the specified locale" do
+      Localize.put_locale(:en)
+      assert url_for(:fr, "/users") == "http://localhost/users_fr"
+      assert url_for(:de, "/users") == "http://localhost/users_de"
+      assert url_for(:en, "/users") == "http://localhost/users"
+    end
+
+    test "supports interpolations" do
+      assert url_for(:de, "/users/:locale") == "http://localhost/users_de/de"
+    end
+  end
+end