# `Localize.Plug.PutLocale`
[🔗](https://github.com/kipcole9/localize_web/blob/main/lib/localize/plug/put_locale.ex#L1)

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 `t: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]

# `get_locale`

Returns the locale set by `Localize.Plug.PutLocale`.

### Arguments

* `conn` is a `t:Plug.Conn.t/0`.

### Returns

* A `t:Localize.LanguageTag.t/0` or `nil`.

# `locale_from_host`

Attempts to resolve a locale from a hostname's top-level domain.

Extracts the TLD, validates it as a territory code, and returns
the best matching locale for that territory.

### Arguments

* `host` is a hostname string (e.g., "example.co.uk").

### Returns

* `{:ok, Localize.LanguageTag.t()}` or

* `{:error, reason}`

# `session_key`

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

### Examples

    iex> Localize.Plug.PutLocale.session_key()
    "localize_locale"

---

*Consult [api-reference.md](api-reference.md) for complete listing*