Puts the Cldr and/or Gettext locales derived from the accept-language header, a query parameter, a url parameter, a body parameter, the route or the session for the current process with Cldr.put_locale/2 and/or Gettext.put_locale/2.

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, :query, :path, :route]. 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
  • :route will look for a locale in the route that was matched under the key private.:cldr_locale. The key may be populated by a Phoenix router and it is used extensively by the ex_cldr_routes library. Note that any locale set in the route represents the locale defined for the route, not necessarily one requested by the user. Therefore setting the locale from the :route key should be a lower priority than other methods based on the actual request.
  • :host will attempt to resolve a locale from the host name top-level domain using Cldr.Locale.locale_from_host/3
  • {Module, function, args} in which case the indicated function will be called. If it returns {:ok, locale} then the locale is set to locale. locale must be a t:Cldr.LanguageTag.t(). Any other return is considered an error and no locale will be set. When calling the function, conn and options will be prepended to args.
  • {Module, function} in which case the function is called with conn and options as its two arguments. All other behaviour is the same as that for a {Module, function, args} option.

• :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. It may also be :none to indicate that no locale is to be set by default. Lastly, it may also be a {Module, function, args} or {Module, function} tuple. The default is Cldr.default_locale/1. If the case of {Module, function, args}, a return of {:ok, %Cldr.LanguageTag{}} will set the locale. Any other return will not set a locale.

• :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 cldr_locale. This option is deprecated and will be removed in a future release. The session key is being standardised in order to faciliate a simpler integration with Phoenix LiveView by ensuring that the session key is always under a well known key.

If a locale is found then conn.private[:cldr_locale] is also set. It can be retrieved with Cldr.Plug.PutLocale.get_cldr_locale/1.

App configuration

The :apps configuration key defines which applications will have their locale set by this plug.

Cldr.Plug.PutLocale 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.PutLocale without Phoenix

If you are using Cldr.Plug.PutLocale without Phoenix and you plan to use :path_param to identify the locale of a request then Cldr.Plug.PutLocale must be configured after plug :match and before plug :dispatch. For example:

defmodule MyRouter do
  use Plug.Router

  plug :match

  plug Cldr.Plug.PutLocale,
    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.PutLocale with Phoenix

If you are using Cldr.Plug.PutLocale with Phoenix and you plan to use the :path_param to identify the locale of a request then Cldr.Plug.PutLocale 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.PutLocale,
        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.PutLocale,
  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.PutLocale,
  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.PutLocale,
  apps:    [cldr: MyApp.Cldr, gettext: :global],
  from:    [:query, :path, :body, :cookie, :accept_language],
  param:   "locale"