Cldr.Plug.SetLocale (Cldr v2.21.0) 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 the accept-language header and finds the best matched configured locale
    • :path will look for a locale by examining conn.path_params
    • :query will look for a locale by examining conn.query_params
    • :body will look for a locale by examining conn.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 a Cldr.LanguageTag struct. The default is Cldr.default_locale/1

  • :gettext - the name of the Gettext 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 the Cldr 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 is locale.

  • :put_session? - defines whether the resolved locale is put in the session. The default is false. If set to true then two items are stored in the session: locale.requested_locale_name is stored under the configured :session_key and the configured backend module is stored in the session under the "cldr_backend" key.

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

# 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"

# 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"

Link to this section Summary

Functions

Return the locale set by Cldr.Plug.SetLocale

Returns the name of the session key used to store the CLDR locale name.

Link to this section Functions

Return the locale set by Cldr.Plug.SetLocale

Returns the name of the session key used to store the CLDR locale name.

Example

iex> Cldr.Plug.SetLocale.session_key() "cldr_locale"