dillonkearns / elm-bcp47-language-tag / LanguageTag

A LanguageTag represents a BCP 47 value, and can be used in the lang attribute of HTML elements to tell the web page which language it's written in, including script and region information.

See https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang.


type LanguageTag


type alias Options =
{ script : Maybe Script
, region : Maybe Region
, variants : List Variant
, extensions : List ExtendedLanguage
, privateUse : Maybe PrivateUse 
}

emptySubtags : Options

This is useful for building up a LanguageTag with no subtags directly:

import LanguageTag
import LanguageTag.Language as Language
import LanguageTag.Region as Region

Language.en
    |> build emptySubtags
    |> LanguageTag.toString
    --> "en"

It's also useful as the starting record for building a LanguageTag that has subtags.

Language.en
    |> build { emptySubtags | region = Just Region.us }
    |> LanguageTag.toString
    --> "en-us"

build : Options -> Language -> LanguageTag

custom : String -> LanguageTag

This is an escape hatch with no validation. It will just directly use the String you pass in. So be sure to test out your LanguageTag that you construct with this function!

If you've encountered a use case that isn't well supported by the current API, please feel free to open a GitHub Issues to share your use case.

unknown : LanguageTag

Unknown tags can be expressed by an empty string in the lang tag (see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang). You may want to set the language as unknown rather than an incorrect specific language to prevent translation plugins from attempting to translate the page incorrectly.

import LanguageTag

LanguageTag.unknown
    |> LanguageTag.toString
    --> ""

toString : LanguageTag -> String

Get a BCP 47 formatted language tag String.

toHtmlAttribute : LanguageTag -> Html.Attribute msg

Most often, you'll want to use BCP 47 tags in the top-level tag <html lang="en-US">. If you have multiple languages on the same page, you can also set the language for individual sections separately.

toParts : LanguageTag -> Maybe ( Language, Options )

If the LanguageTag was not created by custom, get back the components it is made of.

toSegments : LanguageTag -> List String

Return the segments that compose a language tag.

import LanguageTag.Language as Language
import LanguageTag.Region as Region

LanguageTag.custom "x-whatever" |> toSegments
--> [ "x", "whatever" ]

Language.en
    |> build { emptySubtags | region = Just Region.us }
    |> LanguageTag.toSegments
--> [ "en", "us" ]

This is useful for pattern matching with fallback

case LanguageTag.toSegments languageTag of
    "ca" :: "ES" :: "valencia" :: _ ->
        "Catalan - Valencia (Spain)"

    "ca" :: "ES" :: _ ->
        "Catalan - Spain"

    "ca" :: _ ->
        "Catalan"

    "en" :: "GB" :: _ ->
        "English - UK"

    "en" :: _ ->
        "English"