defmodule Cldr.AcceptLanguage do
@moduledoc """
Tokenizer and parser for HTTP `Accept-Language` header values as defined in
[rfc2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4).
The Accept-Language request-header field is similar to Accept, but restricts
the set of natural languages that are preferred as a response to the request.
Language tags function are provided in `Cldr.LanguageTag`.
The format of an `Accept-Language` header is as follows in `ABNF` format:
Accept-Language = "Accept-Language" ":"
1#( language-range [ ";" "q" "=" qvalue ] )
language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
Each language-range MAY be given an associated quality value which represents an
estimate of the user's preference for the languages specified by that range. The
quality value defaults to "q=1". For example,
Accept-Language: da, en-gb;q=0.8, en;q=0.7
would mean: "I prefer Danish, but will accept British English and other types of English."
"""
alias Cldr.Locale
alias Cldr.LanguageTag
@default_quality 1.0
@low_quality 0.2
@doc """
Splits the language ranges for an `Accept-Language` header
value into tuples `{quality, language}`.
* `accept-language` is any string in the format defined by [rfc2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4)
## Example
iex> Cldr.AcceptLanguage.tokenize "da,zh-TW;q=0.3"
[{1.0, "da"}, {0.3, "zh-tw"}]
"""
@spec tokenize(String.t()) :: [{float(), String.t()}, ...]
@language_separator ","
def tokenize(accept_language) do
accept_language
|> String.downcase()
|> remove_whitespace
|> String.split(@language_separator)
|> Enum.reject(&is_nil/1)
|> Enum.reject(&String.starts_with?(&1, "*"))
|> Enum.map(&token_tuple/1)
end
@quality_separator ";q="
defp token_tuple(language) do
case String.split(language, @quality_separator) do
[language, quality] ->
{parse_quality(quality), language}
[language] ->
{@default_quality, language}
[language | _rest] ->
{@low_quality, language}
end
end
@doc """
Parses an `Accept-Language` header value in its string
or tokenized form to return a tuple of the form
`{:ok, [{quality, %Cldr.LanguageTag{}}, ...]}` sorted by quality.
## Arguments
* `accept-language` is any string in the format defined by
[rfc2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4)
* `backend` is any module that includes `use Cldr` and therefore
is a `Cldr` backend module
## Returns
* `{:ok, [{quality, language_tag}, ...]}` or
* `{:error, {Cldr.AcceptLanguageError, String.t}}`
If at least one valid language tag is found but errors are also
detected on one more more tags, an `{ok, list}` tuple is returned
wuth an error tuple for each invalid tag added at the end of the list.
## Example
iex> Cldr.AcceptLanguage.parse("da,zh-TW;q=0.3", TestBackend.Cldr)
{:ok,
[
{1.0,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "da",
cldr_locale_name: :da,
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "da",
locale: %{},
private_use: [],
rbnf_locale_name: :da,
requested_locale_name: "da",
script: :Latn,
territory: :DK,
transform: %{},
language_variants: []
}},
{0.3,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}}
]}
iex> Cldr.AcceptLanguage.parse("invalid_tag", TestBackend.Cldr)
{:error,
{Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \\"g\\" starting at position 11"}}
iex> Cldr.AcceptLanguage.parse("da,zh-TW;q=0.3,invalid_tag", TestBackend.Cldr)
{:ok,
[
{1.0,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "da",
cldr_locale_name: :da,
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "da",
locale: %{},
private_use: [],
rbnf_locale_name: :da,
requested_locale_name: "da",
script: :Latn,
territory: :DK,
transform: %{},
language_variants: []
}},
{0.3,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}},
{:error,
{Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \\"g\\" starting at position 11"}}
]}
"""
@spec parse([{float(), String.t()}, ...] | String.t(), Cldr.backend()) ::
{:ok,
[
{float(), LanguageTag.t()} | {:error, {Cldr.InvalidLanguageTag, String.t()}},
...
]}
| {:error, {Cldr.AcceptLanguageError, String.t()}}
def parse(tokens, backend) when is_list(tokens) do
accept_language =
tokens
|> parse_language_tags(backend)
|> sort_by_quality
case accept_language do
[error: reason] ->
{:error, reason}
_ ->
{:ok, accept_language}
end
end
def parse(string, backend) when is_binary(string) do
string
|> tokenize
|> parse(backend)
end
@doc """
Parses an `Accept-Language` header value in its string
or tokenized form to produce a list of tuples of the form
`[{quality, %Cldr.LanguageTag{}}, ...]` sorted by quality
in descending order.
* `accept-language` is any string in the format defined by [rfc2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4)
Returns:
* `{:ok, [{quality, language_tag}, ...]}` or
* raises a `Cldr.AcceptLanguageError` exception
If at least one valid language tag is found but errors are also
detected on one more more tags, an `{ok, list}` tuple is returned
wuth an error tuple for each invalid tag added at the end of the list.
## Example
iex> Cldr.AcceptLanguage.parse!("da,zh-TW;q=0.3", TestBackend.Cldr)
[
{1.0,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "da",
cldr_locale_name: :da,
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "da",
locale: %{},
private_use: [],
rbnf_locale_name: :da,
requested_locale_name: "da",
script: :Latn,
territory: :DK,
transform: %{},
language_variants: []
}},
{0.3,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}}
]
Cldr.AcceptLanguage.parse! "invalid_tag"
** (Cldr.AcceptLanguageError) "Expected a BCP47 language tag. Could not parse the remaining "g" starting at position 11
(ex_cldr) lib/cldr/accept_language.ex:304: Cldr.AcceptLanguage.parse!/1
iex> Cldr.AcceptLanguage.parse!("da,zh-TW;q=0.3,invalid_tag", TestBackend.Cldr)
[
{1.0,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "da",
cldr_locale_name: :da,
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "da",
locale: %{},
private_use: [],
rbnf_locale_name: :da,
requested_locale_name: "da",
script: :Latn,
territory: :DK,
transform: %{},
language_variants: []
}},
{0.3,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}},
{:error,
{Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \\"g\\" starting at position 11"}}
]
"""
def parse!(accept_language, backend) do
case parse(accept_language, backend) do
{:ok, parse_result} -> parse_result
{:error, {exception, reason}} -> raise exception, reason
end
end
@doc """
Parse an `Accept-Language` string and return the best match for
a configured `Cldr` locale.
* `accept_langauge` is a string representing an accept language header
Returns:
* `{:ok, language_tag}` or
* `{:error, reason}`
## Examples
iex> Cldr.AcceptLanguage.best_match("da;q=0.1,zh-TW;q=0.3", TestBackend.Cldr)
{:ok,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}}
iex> Cldr.AcceptLanguage.best_match("da;q=0.1,zh-TW;q=0.3", TestBackend.Cldr)
{:ok,
%Cldr.LanguageTag{
backend: TestBackend.Cldr,
canonical_locale_name: "zh-TW",
cldr_locale_name: :"zh-Hant",
language_subtags: [],
extensions: %{},
gettext_locale_name: nil,
language: "zh",
locale: %{},
private_use: [],
rbnf_locale_name: :"zh-Hant",
requested_locale_name: "zh-TW",
script: :Hant,
territory: :TW,
transform: %{},
language_variants: []
}}
iex> Cldr.AcceptLanguage.best_match("xx,yy;q=0.3", TestBackend.Cldr)
{:error,
{Cldr.NoMatchingLocale,
"No configured locale could be matched to \\"xx,yy;q=0.3\\""}}
iex> Cldr.AcceptLanguage.best_match("invalid_tag", TestBackend.Cldr)
{:error, {Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \\"g\\" starting at position 11"}}
"""
@spec best_match(String.t(), Cldr.backend()) ::
{:ok, LanguageTag.t()}
| {:error, {Cldr.AcceptLanguageError | Cldr.NoMatchingLocale, String.t()}}
def best_match(accept_language, backend) when is_binary(accept_language) do
with {:ok, languages} <- parse(accept_language, backend) do
candidates =
Enum.filter(languages, fn
{priority, %LanguageTag{cldr_locale_name: locale_name}}
when is_float(priority) and not is_nil(locale_name) ->
true
_ ->
false
end)
case candidates do
[{_priority, language_tag} | _] ->
{:ok, language_tag}
_ ->
{
:error,
{
Cldr.NoMatchingLocale,
"No configured locale could be matched to #{inspect(accept_language)}"
}
}
end
else
{:error, reason} -> {:error, reason}
end
end
@doc """
Filters the returned results of `parse/1` to return
only the error tuples.
## Example
iex> Cldr.AcceptLanguage.parse!("da,zh-TW;q=0.3,invalid_tag", TestBackend.Cldr)
...> |> Cldr.AcceptLanguage.errors
[
error: {Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \\"g\\" starting at position 11"}
]
"""
@spec errors([tuple(), ...]) :: [{:error, {Cldr.InvalidLanguageTag, String.t()}}, ...]
def errors(parse_result) when is_list(parse_result) do
Enum.filter(parse_result, fn
{:error, _} -> true
_ -> false
end)
end
defp parse_quality(quality_string) do
case Float.parse(quality_string) do
:error -> @low_quality
{quality, _} -> quality
end
end
defp parse_language_tags(tokens, backend) do
Enum.map(tokens, fn {quality, language_tag} ->
case Locale.canonical_language_tag(language_tag, backend) do
{:ok, tag} ->
{quality, tag}
{:error, reason} ->
{:error, reason}
end
end)
end
defp remove_whitespace(accept_language) do
String.replace(accept_language, " ", "")
end
def sort_by_quality(tokens) do
Enum.sort(tokens, fn
{:error, _}, {_quality_2, _} -> false
{_quality_2, _}, {:error, _} -> true
{quality_1, _}, {quality_2, _} when quality_1 == quality_2 -> true
{quality_1, _}, {quality_2, _} -> quality_1 > quality_2
end)
end
end
