View Source Cldr.Routes (Cldr Routes v0.1.0)

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 path and URLs.

setting-up

Setting up

A Cldr backend module that configures a Gettext asosciated 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 is configured in 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 english 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. 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 the functional form at compile time, the message ids are not autoamtically populated and must be manually added to the "routes.pot" file for each locale.

Link to this section Summary

Functions

Generates localised routes for each locale defined in a Cldr backend.

Generates localised routes for each locale provided.

Link to this section Functions

Link to this macro

localize(list)

View Source (macro)

Generates localised routes for each locale defined in a Cldr backend.

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

localize do
  get "/pages/:page", PageController, :show
  resources "/users", UsersController
end
Link to this macro

localize(cldr_locale_names, arg2)

View Source (macro)

Generates localised routes for each locale provided.

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

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