Localize.VerifiedRoutes (Localize Web v0.6.0)

Copy Markdown View Source

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

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

  • :locale is replaced with the CLDR locale name.

  • :language is replaced with the CLDR language code.

  • :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"

Summary

Functions

path_for(locale, route)

Generates a localized verified path in a specific locale.

sigil_q(route, flags)

Implements the ~q sigil for localized verified routes.

url(route)

Generates the router url with localized route verification.

url(conn_or_socket_or_endpoint_or_uri, route)

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

url(conn_or_socket_or_endpoint_or_uri, router, route)

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

url_for(locale, route)

Generates a localized verified URL in a specific locale.

Functions

path_for(locale, route)

(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(route, flags)

(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(route)

(macro)

Generates the router url with localized route verification.

url(conn_or_socket_or_endpoint_or_uri, route)

(macro)

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

url(conn_or_socket_or_endpoint_or_uri, router, route)

(macro)

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

url_for(locale, route)

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