Routex.Extension.SimpleLocale (Routex v1.2.0-rc.0)
View SourceExperimental
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 theaccept-language
header.:attrs
uses the (precompiled) route atributes.:body
usesbody_params
; useful when using values in API bodies.:cookie
uses the request cookie(s):host
examines the hostname e.gen.example.com
andexample.nl
. Returns the first match..:path
usespath_params
such as/:language/products/
:query
usesquery_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
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]