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
  • :host will attempt to resolve a locale from the host name top-level domain using Cldr.Locale.locale_from_host/3

• :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.

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"