`elm-bcp47-language-tag`

This package aims to help you build BCP 47 language tags with some type-safety. It's important to note that just because a language tag is valid and correct doesn't mean that it will be supported by browsers and tools. So building up a correct tag with this package should give you added confidence but be sure to test the results.

Project goals

Provide a way to create valid BCP 47 tags with confidence that the result is well-formed and valid.
The resulting Elm bundle will be able to include only the data that is explicitly referenced (for example, LanguageTag.build { emptySubtags | region = Just Region.gb } Language.en only includes the data for the English language and the Great Britain region, but doesn't cause your bundle to include data for French, Spanish, etc.)
For unusual cases, there's an escape hatch (LanguageTag.custom) where you're on your own making sure you have a valid and meaningful value (much like the elm/html API). If you encounter a use case that isn't supported directly and requires this escape hatch, please open a GitHub issue to describe your use case to help me get context!
This package is generated from a script with some data sources, so it can be relatively kept up-to-date through automation.

Why it matters

BCP 47 tags can be used in the lang attribute in HTML elements.
lang attributes are recommended by Lighthouse for the top-level <html> tag
lang attributes can also be used for individual sections of a page, like <p lang="en-GB">...</p><p lang="fr-CA">...</p>
Some CSS, like text-transform, relies on lang tags to determine how to apply capitalize, uppercase, etc. to the content. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform.
Screen readers rely on lang attributes to determine how to pronounce the text. See https://dequeuniversity.com/rules/axe/3.3/html-has-lang.

Out of scope for this package

The current goals for this project are to help you safely construct or parse BCP 47 language tags, in a way that results in good dead-code elimination.

This package is not intended to turn BCP 47 language into human-readable strings (like country or region name, language name, etc.). See supermario/elm-countries for a package that lets you find the country name for a given ISO 3166 country.

Some reasons that this use case doesn't fit into the package goals currently:

Metadata, like country or region name, language name, etc. is more likely to change frequently. Hopefully the narrowly focused goal of this package will allow it to have less churn since it only changes the codes (like country or region code, language code, etc.) change. The package will not change and require an update when names or other metadata change.
Turning a code, like a language code or country code, into a name, like a language name or a country name, requires including the data for all possible values in your bundle.

Usage

import LanguageTag exposing (emptySubtags)
import LanguageTag.Language as Language
import LanguageTag.Region as Region
import LanguageTag.Script as Script
import LanguageTag.Variant as Variant

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

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

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

Language.hy
    |> LanguageTag.build
        { emptySubtags |
          region = Just Region.it
        , script = Just Script.latn
        , variants = [ Variant.arevela ]
        }
    |> LanguageTag.toString
    --> "hy-latn-it-arevela"

-- Chinese, Simplified script, as used in China
Language.zh
    |> LanguageTag.build { emptySubtags | region = Just Region.cn, script = Just Script.hans }
    |> LanguageTag.toString
    --> "zh-hans-cn"

Custom Tags

The following features and tag types are supported indirectly through the custom constructor that lets you supply your own custom string:

Reference

Learn more about the BCP 47 spec at https://www.w3.org/International/questions/qa-choosing-language-tags.

dillonkearns / elm-bcp47-language-tag