I18Next

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.

Types and Data

type Translations

A type that represents your loaded translations
type Delims
= Curly
| Underscore
| Custom ({ opening : String, closing : String })

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.
type alias Replacements = Array { placeholder : String, replacement : 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.
type alias CustomReplacements a = Array { placeholder : String, replacement : 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.

Decoding

Turn your JSON into translations.

translationsDecoder : 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 Gren 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

Using Translations

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" [{ placeholder = "name", replacement = "Peter"}]
tf : Array 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 :
Array 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
  langArray = [germanTranslations, englishTranslations]
in
  trf langArray Curly "greet"
    [{ placeholder = "name", replacement = "Peter")] -- "Hello Peter"
customTr :
Translations
-> Delims
-> (String -> a)
-> String
-> CustomReplacements a
-> Array a

Sometimes it can be useful to replace placeholders with other things than just Strings. 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 {{gren-website}} for more information." }
...
-}
import Html exposing (text, a)

customTr translationsEn Curly text "call-to-action"
    [ { placeholder = "gren-website", replacement = a
        [href "https://gren-lang.org"] [text "https://gren-lang.org"] } ]
-- Go to <a href="https://gren-lang.org">https://gren-lang.org</a> for more information.

If you only want Strings though, use tr instead.
customTrf :
Array Translations
-> Delims
-> (String -> a)
-> String
-> CustomReplacements a
-> Array a

Like customTr but with support for fallback languages.

Inspecting

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 -> Array 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 -> Bool

This function lets you check whether a certain key is exists in your translations.

Creating Translations Programmatically

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.

type Tree

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 : Array { label : String, item : Tree } -> Translations

Create a Translations value from a list of pairs.

import I18Next exposing (string, object, fromTree, t)

translations =
    fromTree
      [ { label = "custom"
        , item = object
            [ { label = "morning", item = string "Morning" }
            , { label = "evening", item = string "Evening" }
            , { label = "afternoon", item = string "Afternoon" }
            ]
        )
      , { label = "hello", item = 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 : Array { label : String, item : Tree } -> Tree

Let's you arrange your translations in a hierarchy of objects.