Cldr v2.20.0-rc.0 Cldr.Plug.SetLocale View Source
Sets the Cldr and/or Gettext locales derived from the accept-language header, a query parameter, a url parameter, a body parameter or the session.
Options
:apps
- list of apps for which to set locale. See the apps configuration section.:from
- where in the request to look for the locale. The default is[:session, :accept_language]
. The valid options are::accept_language
will parse theaccept-language
header and finds the best matched configured locale:path
will look for a locale by examiningconn.path_params
:query
will look for a locale by examiningconn.query_params
:body
will look for a locale by examiningconn.body_params
:cookie
will look for a locale in the request cookie(s):session
will look for a locale in the session
:default
- the default locale to set if no locale is found by other configured methods. It can be a string like "en" or aCldr.LanguageTag
struct. The default isCldr.default_locale/1
:gettext
- the name of theGettext
backend module upon which the locale will be validated. This option is not required if a gettext module is specified in the:apps
configuration.:cldr
- the name of theCldr
backend module upon which the locale will be validated. This option is not required if a gettext module is specified in the:apps
configuration.:session_key
- defines the key used to look for the locale in the session. The default islocale
.
If a locale is found then conn.private[:cldr_locale]
is also set.
It can be retrieved with Cldr.Plug.SetLocale.get_cldr_locale/1
.
App configuration
The :apps
configuration key defines which applications will have
their locale set by this plug.
Cldr.Plug.SetLocale
can set the locale for cldr
, gettext
or both.
The basic configuration of the :app
key is an atom, or list of atoms,
containing one or both of these app names. For example:
apps: :cldr
apps: :gettext
apps: [:cldr, :gettext]
In each of these cases, the locale is set globally for the current process.
Sometimes setting the locale for only a specific backend is required.
In this case, configure the :apps
key as a keyword list pairing an
application with the required backend module. The value :global
signifies
setting the local for the global context. For example:
apps: [cldr: MyApp.Cldr]
apps: [gettext: MyAppGettext]
apps: [gettext: :global]
apps: [cldr: MyApp.Cldr, gettext: MyAppGettext]
Using Cldr.Plug.SetLocale without Phoenix
If you are using Cldr.Plug.SetLocale
without Phoenix and you
plan to use :path_param
to identify the locale of a request
then Cldr.Plug.SetLocale
must be configured after plug :match
and before plug :dispatch
. For example:
defmodule MyRouter do
use Plug.Router
plug :match
plug Cldr.Plug.SetLocale,
apps: [:cldr, :gettext],
from: [:path, :query],
gettext: MyApp.Gettext,
cldr: MyApp.Cldr
plug :dispatch
get "/hello/:locale" do
send_resp(conn, 200, "world")
end
end
Using Cldr.Plug.SetLocale with Phoenix
If you are using Cldr.Plug.SetLocale
with Phoenix and you plan
to use the :path_param
to identify the locale of a request then
Cldr.Plug.SetLocale
must be configured in the router module, not
in the endpoint module. This is because conn.path_params
has
not yet been populated in the endpoint. For example:
defmodule MyAppWeb.Router do
use MyAppWeb, :router
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug Cldr.Plug.SetLocale,
apps: [:cldr, :gettext],
from: [:path, :query],
gettext: MyApp.Gettext,
cldr: MyApp.Cldr
plug :fetch_flash
plug :protect_from_forgery
plug :put_secure_browser_headers
end
scope "/:locale", HelloWeb do
pipe_through :browser
get "/", PageController, :index
end
end
Examples
# Will set the global locale for the current process
# for both `:cldr` and `:gettext`
plug Cldr.Plug.SetLocale,
apps: [:cldr, :gettext],
from: [:query, :path, :body, :cookie, :accept_language],
param: "locale",
gettext: GetTextModule,
cldr: MyApp.Cldr
session_key: "cldr_locale"
# Will set the backend-only locale for the current process
# for both `:cldr` and `:gettext`
plug Cldr.Plug.SetLocale,
apps: [cldr: MyApp.Cldr, gettext: GetTextModule],
from: [:query, :path, :body, :cookie, :accept_language],
param: "locale",
session_key: "cldr_locale"
# Will set the backend-only locale for the current process
# for `:cldr` and globally for `:gettext`
plug Cldr.Plug.SetLocale,
apps: [cldr: MyApp.Cldr, gettext: :global],
from: [:query, :path, :body, :cookie, :accept_language],
param: "locale",
session_key: "cldr_locale"
Link to this section Summary
Functions
Return the locale set by Cldr.Plug.SetLocale
Link to this section Functions
Return the locale set by Cldr.Plug.SetLocale