View Source Cldr Routes

Generate localized routes and route helper modules.

This module when used , provides a localize/1 macro that is designed to wrap the standard Phoenix route macros such as get/3, put/3 and resources/3 and localises them for each locale defined in a Gettext backend module attached to a Cldr backend module.

Translations for the parts of a given route path are translated at compile-time which are then combined into a localised route that is added to the standard Phoenix routing framework.

As a result, users can enter URLs using localised terms which can enhance user engagement and content relevance.

Similarly, a localised path and URL helpers are generated that wrap the standard Phoenix helpers to supporting generating localised paths and URLs.

setting-up

Setting up

A Cldr backend module that configures an associated gettext backend is required.

Path parts (the parts between "/") are translated at compile time using Gettext. Therefore localization can only be applied to locales that are defined in a gettext backend module that attached to a Cldr backend module. For example:

defmodule MyApp.Cldr do
  use Cldr,
    locales: ["en", "fr"],
    default_locale: "en".
    gettext: MyApp.Gettext
    providers: [Cldr.Routes]

end

Here the MyApp.Cldr backend module is used to instrospect the configured locales in order to drive the localization generation.

Next, configure the router module to use the localize/1 macro by adding use MyApp.Cldr.Routes to the module and invoke the localize/1 macro to wrap the required routes. For example:

defmodule MyApp.Router do
  use Phoenix.Router
  use MyApp.Cldr.Routes

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

The following routes are generated (assuming that translations are updated in the Gettext configuration). For this example, the :fr translations are the same as the :en text with _fr appended.

% mix phx.routes MyApp.Router
 page_path  GET     /pages/:page        PageController :show
 page_path  GET     /pages_fr/:page     PageController :show
users_path  GET     /users              UsersController :index
users_path  GET     /users/:id/edit     UsersController :edit
users_path  GET     /users/new          UsersController :new
users_path  GET     /users/:id          UsersController :show
users_path  POST    /users              UsersController :create
users_path  PATCH   /users/:id          UsersController :update
            PUT     /users/:id          UsersController :update
users_path  DELETE  /users/:id          UsersController :delete
users_path  GET     /users_fr           UsersController :index
users_path  GET     /users_fr/:id/edit  UsersController :edit
users_path  GET     /users_fr/new       UsersController :new
users_path  GET     /users_fr/:id       UsersController :show
users_path  POST    /users_fr           UsersController :create
users_path  PATCH   /users_fr/:id       UsersController :update
            PUT     /users_fr/:id       UsersController :update
users_path  DELETE  /users_fr/:id       UsersController :delete

translations

Translations

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

Using the example Cldr backend that has "en" and "fr" Gettext locales then the directory structure would look like the following (if the default Gettext configuration is used):

priv/gettext
 default.pot
 en
    LC_MESSAGES
        default.po
        errors.po
        routes.po
 errors.pot
 fr
     LC_MESSAGES
         default.po
         errors.po
         routes.po

Note that since the translations are performed with Gettext.dgettext/3 at compile time, the message ids are not autoamtically populated and must be manually added to the "routes.pot" file for each locale. That is, the mix tasks mix gettext.extract and mix gettext.merge will not detect or extract the route segments.

path-helpers

Path Helpers

In the same way that Phoenix generates a MyApp.Router.Helpers module, ex_cldr_routes also generates a MyApp.Router.LocalizedHelpers module that translates localized paths. Since this module is generated alongside the standard Helpers module, an application can decide to generate either canonical paths or localized paths. Here are some examples, assuming the same Cldr and Gettext configuration as the previous examples:

iex> MyApp.Router.LocalizedHelpers.page_path %Plug.Conn{}, :show, 1
"/pages/1"
iex> Gettext.put_locale MyAppWeb.Gettext, "fr"         
nil
iex> MyApp.Router.LocalizedHelpers.page_path %Plug.Conn{}, :show, 1
"/pages_fr/1"

assigns

Assigns

For each localized path, the Cldr locale is added to the :assigns for the route under the :cldr_locale key. This allows the developer to recognise which locale was used to generate the localized route.

installation

Installation

The package can be installed by adding ex_cldr_routes to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_cldr_routes, "~> 0.1.0"}
  ]
end

The docs canbe found at https://hexdocs.pm/ex_cldr_routes.