Plug that discovers and sets the locale for the current process.

The locale can be derived from the accept-language header, a query parameter, a URL parameter, a body parameter, a cookie, the route, the session, or the hostname TLD. Sources are checked in the order specified by the :from option, and the first successful match wins.

When a locale is found, Localize.put_locale/1 is always called to set the process locale. If Gettext backends are configured, the locale is also set on each backend.

If a locale is found then conn.private[:localize_locale] is also set. It can be retrieved with Localize.Plug.PutLocale.get_locale/1.

Options

• :from is a list specifying 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 find 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.:localize_locale.

  • :host will attempt to resolve a locale from the hostname top-level domain.

  • {Module, function, args} in which case the indicated function will be called. If it returns {:ok, locale} then the locale is set. locale must be a Localize.LanguageTag.t/0.

  • {Module, function} in which case the function is called with conn and options as its two arguments.

• :default is the default locale to set if no locale is found by other configured methods. It can be a string like "en" or a Localize.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 Localize.default_locale/0.

• :gettext is a Gettext backend module or a list of Gettext backend modules on which the locale will be set. The default is [] (no Gettext backends).

• :param is the name of the parameter to look for in the query, path, body, or cookie. The default is "locale".

Examples

plug Localize.Plug.PutLocale,
  from: [:query, :path, :body, :cookie, :accept_language],
  param: "locale",
  gettext: MyApp.Gettext

plug Localize.Plug.PutLocale,
  from: [:route, :session, :accept_language],
  gettext: [MyApp.Gettext, MyOtherApp.Gettext]