# `Localize.VerifiedRoutes`
[🔗](https://github.com/elixir-localize/localize_web/blob/main/lib/localize/routes/verified_routes.ex#L1)

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"

# `path_for`
*macro* 

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"]

# `sigil_q`
*macro* 

Implements the `~q` sigil for localized verified routes.

Generates a `case` expression that dispatches to the translated `~p` route for the current locale. The route path is verified at compile time against the router.

# `url`
*macro* 

Generates the router url with localized route verification.

# `url`
*macro* 

Generates the router url with localized route verification from the
connection, socket, or URI.

# `url`
*macro* 

Generates the router url with localized route verification from the
connection, socket, or URI and router.

# `url_for`
*macro* 

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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*