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.

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

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 for all backends for the current process. This is the preferred model.

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 :all signifies setting the local for all backends. For example:

apps: [cldr: MyApp.Cldr]
apps: [gettext: MyAppGettext]
apps: [gettext: :all]
apps: [cldr: MyApp.Cldr, gettext: MyAppGettext]

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 for all backends for `:gettext`
plug Cldr.Plug.SetLocale,
  apps:    [cldr: MyApp.Cldr, gettext: :all],
  from:    [:query, :path, :body, :cookie, :accept_language],
  param:   "locale",
  session_key: "cldr_locale"