This library provides a solution to load and display translations in your app. It allows you to load json translation files, display the text and interpolate placeholders. There is also support for fallback languages if needed.
A type that represents your loaded translations
A union type for representing delimiters for placeholders. Most commonly
those will be {{...}}
, or __...__
. You can also provide a set of
custom delimiters(start and end) to account for different types of placeholders.
List ( String
, String
}
An alias for replacements for use with placeholders. Each tuple should
contain the name of the placeholder as the first value and the value for
the placeholder as the second entry. See tr
and
trf
for usage examples.
List ( String, a )
CustomReplacements if you want to replace placeholders with other things
than strings. The tuples should
contain the name of the placeholder as the first value and the value for
the placeholder as the second entry. It can be anything, for example Html
. See customTf
and
customTrf
for usage examples.
initialTranslations : Translations
Use this to initialize Translations in your model. This may be needed when loading translations but you need to initialize your model before your translations are fetched.
Turn your JSON into translations.
translationsDecoder : Json.Decode.Decoder Translations
Decode a JSON translations file. The JSON can be arbitrarly nested, but the leaf values can only be strings. Use this decoder directly, if you are passing the translations JSON into your elm app via flags or ports. After decoding nested values will be available with any of the translate functions separated with dots.
{- The JSON could look like this:
{
"buttons": {
"save": "Save",
"cancel": "Cancel"
},
"greetings": {
"hello": "Hello",
"goodDay": "Good Day {{firstName}} {{lastName}}"
}
}
-}
--Use the decoder like this on a string
import I18Next exposing (translationsDecoder)
Json.Decode.decodeString translationsDecoder "{ \"greet\": \"Hello\" }"
-- or on a Json.Encode.Value
Json.Decode.decodeValue translationsDecoder encodedJson
Get translated values by key straight away, with replacements, fallback languages or both.
t : Translations -> String -> String
Translate a value at a given string.
{- If your translations are { "greet": { "hello": "Hello" } }
use dots to access nested keys.
-}
import I18Next exposing (t)
t translations "greet.hello" -- "Hello"
tr : Translations -> Delims -> String -> Replacements -> String
Translate a value at a key, while replacing placeholders.
Check the Delims
type for
reference how to specify placeholder delimiters.
Use this when you need to replace placeholders.
-- If your translations are { "greet": "Hello {{name}}" }
import I18Next exposing (tr, Delims(..))
tr translations Curly "greet" [("name", "Peter")]
tf : List Translations -> String -> String
Translate a value and try different fallback languages by providing a list of Translations. If the key you provide does not exist in the first of the list of languages, the function will try each language in the list.
{- Will use german if the key exists there, or fall back to english
if not. If the key is not in any of the provided languages the function
will return the key. -}
import I18Next exposing (tf)
tf [germanTranslations, englishTranslations] "labels.greetings.hello"
trf : List Translations -> Delims -> String -> Replacements -> String
Combines the tr
and the tf
function.
Only use this if you want to replace placeholders and apply fallback languages
at the same time.
-- If your translations are { "greet": "Hello {{name}}" }
import I18Next exposing (trf, Delims(..))
let
langList = [germanTranslations, englishTranslations]
in
trf langList Curly "greet" [("name", "Peter")] -- "Hello Peter"
customTr : Translations -> Delims -> (String -> a) -> String -> CustomReplacements a -> List a
Sometimes it can be useful to replace placeholders with other things than just String
s.
Imagine you have translations containing a sentence with a link and you want to
provide the proper markup.
Hint: The third argument is a function which will be called for any string pieces that
AREN'T placeholders, so that the types of replacements and the other other string parts match.
In most cases you'll just pass Html.text
here.
{- If your translations are { "call-to-action": "Go to {{elm-website}} for more information." }
...
-}
import Html exposing (text, a)
customTr translationsEn Curly text "call-to-action" [ ( "elm-website", a [href "https://elm-lang.org"] [text "https://elm-lang.org"] ) ]
-- Go to <a href="https://elm-lang.org">https://elm-lang.org</a> for more information.
If you only want String
s though, use tr
instead.
customTrf : List Translations -> Delims -> (String -> a) -> String -> CustomReplacements a -> List a
Like customTr
but with support for fallback languages.
You probably won't need these functions for regular applications if you just want to translate some strings. But if you are looking to build a translations editor you might want to query some information about the contents of the translations.
keys : Translations -> List String
Use this to obtain a list of keys that are contained in the translations. From this it is simple to, for example, compare two translations for keys defined in one but not the other. The order of the keys is arbitrary and should not be relied on.
hasKey : Translations -> String -> Basics.Bool
This function lets you check whether a certain key is exists in your translations.
Most of the time you'll load your translations as JSON from a server, but there
may be times, when you want to build translations in your code. The following
functions let you build a Translations
value programmatically.
A type representing a hierarchy of nested translations. You'll only ever
deal with this type directly, if you're using
string
and object
.
fromTree : List ( String, Tree ) -> Translations
Create a Translations
value from a list of pairs.
import I18Next exposing (string, object, fromTree, t)
translations =
fromTree
[ ("custom"
, object
[ ( "morning", string "Morning" )
, ( "evening", string "Evening" )
, ( "afternoon", string "Afternoon" )
]
)
, ("hello", string "hello")
]
-- use it like this
t translations "custom.morning" -- "Morning"
string : String -> Tree
Represents the leaf of a translations tree. It holds the actual translation string.
object : List ( String, Tree ) -> Tree
Let's you arange your translations in a hierarchy of objects.