Localized verified routes using the ~q sigil.

This module provides compile-time verified localized routes. Instead of configuring with use Phoenix.VerifiedRoutes, configure instead:

use Localize.VerifiedRoutes,
  router: MyApp.Router,
  endpoint: MyApp.Endpoint,
  gettext: MyApp.Gettext,
  statics: MyAppWeb.static_paths()

Only :gettext is consumed here; every other option is passed through to Phoenix.VerifiedRoutes unchanged. Keep whatever the generated MyAppWeb.verified_routes/0 already passed — in particular :statics, without which ~p"/images/logo.svg" and the other asset paths in the default layouts warn that no route matches them.

When configured, the sigil ~q is made available to express localized verified routes. Sigil ~p remains available for non-localized verified routes.

The ~q sigil generates a case statement that dispatches to the appropriate localized ~p route based on the current locale:

# ~q"/users" generates:
case Localize.get_locale().cldr_locale_id do
  :de -> ~p"/benutzer"
  :en -> ~p"/users"
  :fr -> ~p"/utilisateurs"
end

Locale Interpolation

A path may embed the current locale in one of its segments. Three tokens are recognised:

• locale is replaced with the CLDR locale name.

• language is replaced with the CLDR language code.

• territory is replaced with the CLDR territory code.

Each is written in one of two forms, and both resolve at compile time, once per locale branch:

~q"/#{locale}/pages/intro"     # interpolation form
~q"/:locale/pages/intro"       # colon form

The interpolation form looks like ordinary Elixir interpolation but is not — locale is a token recognised by the sigil, not a variable, and no binding of that name is consulted. It is the form to prefer, because it is the only one the Localize.Routes.localize/1 macro accepts when defining routes: in a router, :locale is an ordinary Phoenix path parameter and is left alone.

# in the router
localize do
  get "/#{locale}/pages/:page", PageController, :show
end

# in a template, matching that route
~q"/#{locale}/pages/intro"

The colon form is accepted in ~q for convenience and has no router counterpart.

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"