ccapndave/elm-translator/1.2.0

NOTE: this package is not compatible with Elm 0.19.1

Translator

A package to provide type safe internationalisation, where translations can be loaded at runtime. Default translations, substitutions and pluralization are supported.

Substitutions are implemented by surrounding the literal in braces:

"MyNameIs": "Je m'appelle {name}"

Pluralization is implemented by having the singular case on the left of the pipe symbol, and all other cases on the right. The number can be substituted using {count}.

"MyAge": "I am only one year old|I'm {count} years old"

See the example/ directory for an example of the package being used.

Building Translators

type alias Translator =
{ defaultTranslations : Translations
, translations : Maybe Translations
}

A Translator contains all the required information to translate strings into other languages.

makeDefaultTranslator : Translations -> Translator

This creates a Translator with the given default Translations, but no loaded Translations. Typically this would be used when initializing your program's Model to make sure there are some translations on startup.

updateTranslations : Translations -> Translator -> Translator

Update an existing Translator with the given loaded Translations. Typically this would be used to update an existing Translator when you have loaded some Translations at runtime.

getTranslations : Translator -> Maybe Translations

Get the translations out of the Translator (if there are any).

decoderFromTranslationsWithDefault : Translations -> Decoder Translator

This creates a Json Decoder that will decode Json of the form:

{
    "Yes": "Oui",
    "No": "Non"
}

into a valid Translator that can be used with the translation functions in this package. You need to provide a Translations parameter which contains the default translations, in case a translation can't be matched.

decoderToUpdateTranslations : Translator -> Decoder Translator

This creates a Json Decoder that will decode Json of the form:

{
    "Yes": "Oui",
    "No": "Non"
}

into a valid Translator that can be used with the translation functions in this package. You need to provide a Translator parameter which contains an existing translator; the default translations will be kept from this Translator.

Using Translators

trans : literal -> Translator -> String

Given an id and a Translator, translate to a String. This can never fail, and in the event of being unable to match in either the loaded or default literals this will fall back to "...". This supports substitutions and pluralization.

Substitutions and pluralization are supported (see the top-level package doumentation).

transString : String -> Translator -> String

This is identical to trans, except that it takes the name of the literal as a String instead of the Literal itself. This is useful when the literal's name is loaded dynamically. Because we don't have access to the type constructor this doesn't support substitutions.

text : Translator -> literal -> Html msg

A translated version of Html.text for use directly in an Elm view

placeholder : Translator -> literal -> Attribute msg

A translated version of Html.Attributes.placeholder for use directly in an Elm view