Localize.Routes (Localize Web v1.3.0)

Copy Markdown View Source

Compile-time route localization for Phoenix routers.

When used, this module provides a localize/1 macro that wraps standard Phoenix route macros such as get/3, put/3 and resources/3, generating localized versions for each locale defined in a Gettext backend module.

Path segments are translated at compile time using Gettext's dgettext/3 with the "routes" domain. The translated paths are added to the standard Phoenix routing framework alongside the original routes.

Configuration

A Gettext backend module is required. Path segments (the parts between /) are translated at compile time. Therefore localization can only be applied to locales that are defined in a Gettext backend module.

For example:

defmodule MyApp.Router do
  use Phoenix.Router
  use Localize.Routes, gettext: MyApp.Gettext

  localize do
    get "/pages/:page", PageController, :show
    resources "/users", UserController
  end
end

Interpolating Locale Data

A route may be defined with elements of the locale interpolated into it. These interpolations are specified using the normal #{} interpolation syntax. However since route translation occurs at compile time only the following interpolations are supported:

  • locale will interpolate the CLDR locale name.

  • language will interpolate the language code.

  • territory will interpolate the territory code.

Localized Live Routes

Define localized live routes inside localize_live_session/3 rather than Phoenix.LiveView.Router.live_session/3. It puts each locale's routes into their own live session, so a live navigation to another locale is a full page load in that locale.

Localized Helpers

A LocalizedHelpers module is generated at compile time. Assuming the router module is called MyApp.Router then the full name of the localized helper module is MyApp.Router.LocalizedHelpers.

Localized helpers can be disabled by adding helpers: false to the use Localize.Routes line in your router module.

Translations

In order for routes to be localized, translations must be provided for each path segment. This translation is performed by Gettext.dgettext/3 with the domain "routes". Therefore for each configured locale, a routes.po file is required containing the path segment translations for that locale.

Summary

Functions

localize(list)

Generates localised routes for each locale defined in the configured Gettext backend.

localize(locale_ids, arg2)

Generates localised routes for each locale provided.

localize_live_session(name, options \\ [], list)

Defines one LiveView live session per locale, each holding that locale's localized routes.

Functions

localize(list)

(macro)

Generates localised routes for each locale defined in the configured Gettext backend.

This macro is intended to wrap a series of standard route definitions in a do block. For example:

localize do
  get "/pages/:page", PageController, :show
  resources "/users", UsersController
end

localize(locale_ids, arg2)

(macro)

Generates localised routes for each locale provided.

This macro is intended to wrap a series of standard route definitions in a do block. For example:

localize [:en, :fr] do
  get "/pages/:page", PageController, :show
  resources "/users", UsersController
end

localize_live_session(name, options \\ [], list)

(since 1.2.0) (macro)

Defines one LiveView live session per locale, each holding that locale's localized routes.

A live navigation mounts the next LiveView over the existing socket: no plug runs, the root layout (<html lang>, hreflang links) is not rendered again, and the on_mount callbacks receive the session of the page the navigation started from. So a live navigation from /en/video to /fr/vidéo would render the French route in English.

LiveView performs a full page load whenever a navigation crosses from one live session into another. This macro puts each locale's routes into their own live session, so a navigation to another locale reloads the page and runs the plug pipeline, while navigation within one locale stays live. Each live session also sets the locale in the LiveView session under the key "localize_locale", so an on_mount callback that calls Localize.Plug.put_locale_from_session/2 sets the locale of the route being mounted.

Arguments

  • name is an atom naming the live session. Each locale's live session is named :"#{name}_#{locale}", for example :default_fr.

  • options is a keyword list of options passed to Phoenix.LiveView.Router.live_session/3.

  • block holds the routes. Every route in it must be inside a localize/1 or localize/2 block, since any other route would be defined once per locale. scope/2 and pipe_through/1 may be used as usual.

Options

  • :on_mount, :layout and :root_layout are passed to each live session unchanged.

  • :session is a map or a {module, function, args} tuple, as for Phoenix.LiveView.Router.live_session/3. The locale of each live session is added to the session it produces.

Returns

  • One Phoenix.LiveView.Router.live_session/3 definition per locale known to the Gettext backend, each holding the block's routes for that locale.

  • Raises ArgumentError at compile time when options is not a keyword list, or when a route in the block is not inside a localize block.

Examples

localize_live_session :default, on_mount: [MyAppWeb.LocaleLive] do
  scope "/", MyAppWeb do
    localize do
      live "/#{locale}/video", VideoLive
      live "/#{locale}/audio", AudioLive
    end
  end
end

Live routes that are not localized belong in a separate live_session/3. A navigation between them and a localized route is then a full page load.