Routex.Extension.SimpleLocale (Routex v1.2.0-rc.0)

View Source

Experimental

This module is experimental and may be subject to change

Compile time - During compilation this extension expands the locale attribute into locale, language, region, language_display_name and region_display_name using the included locale registry (see below).

Run time - It provides a Liveview lifecycle hook and a Plug to set the locale, language and region attributes at runtime from a configurable source. Each fields source can be independently derived from the accept-language header, a query parameter, a url parameter, a body parameter, the route or the session for the current process.

This extensions comes with a simple locale registry covering common needs. The language/1 and region/1 functions can be used to translate locale, region and language identifiers to display names. language? and region? validate input.

Supports languages and regions defined in the IANA Language Subtag Registry

In combination with...

This extension sets Routex.Attrs during runtime. To use these attributes in other libraries / packages such as Gettext and Cldr, refer to Routex.Extension.RuntimeCallbacks

Options

Fields

Multiple fields can be configured with suffixes _sources and _params. By default, region and language are derived from locale.

  • :locale
  • :region
  • :language

Sources

List of sources to examine for this field. The valid options are:

  • :accept_language examines the accept-language header.
  • :attrs uses the (precompiled) route atributes.
  • :body uses body_params; useful when using values in API bodies.
  • :cookie uses the request cookie(s)
  • :host examines the hostname e.g en.example.com and example.nl. Returns the first match..
  • :path uses path_params such as /:language/products/
  • :query uses query_params such as /products?language=nl
  • :session uses the session

Default: [:query, :session, :cookie, :accept_language, :path, :attrs]

Params

List of keys in a source to get. Defaults to the name of the field with fallback to locale.

## Example configuration

# file lib/example_web/routex_backend.ex
defmodule ExampleWeb.RoutexBackend do
use Routex.Backend,
extensions: [
  Routex.Extension.Attrs,
+     Routex.Extension.SimpleLocale,
+     Routex.Extension.RuntimeCallbacks  # when using callbacks to other libraries
],
+ # Below is for demonstration only. Use sensible values (or keep commented)
+ # region_sources: [:accept_language, :attrs],
+ # region_params: ["region"],
+ # language_sources: [:query, :attrs],
+ # language_params: ["language"],
+ # locale_sources: [:query, :session, :accept_language, :attrs],
+ # locale_params: ["locale"]

# using RuntimeCallbacks to call Gettext.put_locale
+      runtime_callbacks: [
+        # Set Gettext locale from :language attribute
+        {Gettext, :put_locale, [[:attrs, :language]]},
+       ]

Routex.Attrs

Requires

  • none

Sets

  • none

Helpers

runtime_callbacks(attrs :: T.attrs) :: :ok

Summary

Functions

Hook attached to the handle_params stage in the LiveView life cycle. Inlined by Routex.

Plug added to the Conn lifecycle. Inlined by Routex.

Expands the attributes to include: [:language, :region, :language_display_name, :region_display_name]

Functions

handle_params(params, url, socket, attrs \\ %{})

Hook attached to the handle_params stage in the LiveView life cycle. Inlined by Routex.

plug(conn, opts, attrs \\ %{})

Plug added to the Conn lifecycle. Inlined by Routex.

transform(routes, backend, env)

Expands the attributes to include: [:language, :region, :language_display_name, :region_display_name]