View Source Cldr.Routes (Cldr Routes v0.1.0)
Generate localized routes and route helper modules.
This module when use
d , 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
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
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