ndortega / elm-gtranslate / GTranslate.Free

The goal of this library is to provide a type-safe way to interact with the Google Translation api. This project will eventually come in two flavors: Free & Official. Currently, only the Free module is implemented which allows you to make a limited number of translations / minute.

Core Functions

These functions are helpful when you want to translate one thing at a time.

translate : Maybe String -> Config a msg -> String -> Platform.Cmd.Cmd msg

Translates text from a specific language into another specific language. This function takes an optional string which can be used to 'id' or 'tag' this translation, a config, and the source text you want to translate.

For a comprehensive list of supported languages, go [here.](https://cloud.google.com/translate/docs/languages)

import Http
import GTranslate.Free exposing (Translation, translate)

-- MESSAGE
type Msg
    = Response (Result Http.Error Translation )
    | Translate String

-- our configuration record used in the application
customConfig : Config String Msg
customConfig =
    Response -- 'Response' is our message
        |> initConfig "en"      -- specify that english is our target language
        |> withSourceLang "es"  -- specify that spanish is our source language

-- UPDATE
update : Msg -> Model -> ( Model, Cmd Msg )
update message model =
    case message of

        Translate text ->
            -- Translate the 'text' input variable
            (model, translate Nothing customConfig text ) -- translate spanish (es) to english (en)

        Response (Ok translation) ->
            -- do something with the translation
            (model, Cmd.none)

        Response (Err msg) ->
            -- handle error here
            (model, Cmd.none)

toEnglish : (Result Http.Error Translation -> msg) -> String -> Platform.Cmd.Cmd msg

Translate any language into english. For a comprehensive list of supported languages, go here.

import GTranslate.Free exposing (Translation, toEnglish)
import Http


-- MESSAGE
type Msg
    = Response (Result Http.Error Translation)
    | Translate String

-- UPDATE
update : Msg -> Model -> ( Model, Cmd Msg )
update message model =
    case message of
        Translate text ->
            ( model, toEnglish Response text )

        -- translate any language to english
        Response (Ok translation) ->
            -- do something with the translation
            ( model, Cmd.none )

        Response (Err msg) ->
            -- handle error here
            ( model, Cmd.none )

toTargetLang : (Result Http.Error Translation -> msg) -> String -> String -> Platform.Cmd.Cmd msg

Convert any language to a target language. For a comprehensive list of supported languages, go here.

import GTranslate.Free exposing (Translation, toTargetLang)
import Http


-- MESSAGE
type Msg
    = Response (Result Http.Error Translation)
    | Translate String

-- UPDATE
update : Msg -> Model -> ( Model, Cmd Msg )
update message model =
    case message of
        Translate text ->
            ( model, toTargetLang Response "hy" text )

        -- translate any language to Armenian
        Response (Ok translation) ->
            -- do something with the translation
            ( model, Cmd.none )

        Response (Err msg) ->
            -- handle error here
            ( model, Cmd.none )

Advanced Functions

These functions are useful when you want to translate many things at the same time. Tranlsations like these are done simulataneously and will not execute in any order.

batchStrings : Config String msg -> List String -> Platform.Cmd.Cmd msg

Convience function used translate a list of strings from one language to another. Each translation is assigned an id (as a String) which is just the index of the text in the list.

batchRecords : Config a msg -> (a -> String) -> List a -> Platform.Cmd.Cmd msg

Convience function used translate a list of custom records from one language to another. Each translation is assigned an id (as a String) based on the given UID generator function. If no function is present in the config, then each record is assigned a string representing the index it appears in the list. You can see an example usuage of this function in the 'apply' function example.

apply : Config a msg -> (Translation -> a -> a) -> List Translation -> List a -> List a

This function is your bread & butter when it comes to handling bulk translations. This function takes a config type, an update function, a list of translations, and the list of records you want to apply the translations to. If a uid generator is provided in the config this function will use that to lookup the matching record to update. If no uid generator is provided, then this function will automatically sort the list of translations to match the original order of your records. Afterwards, this function will step over both lists and update each translation with the adjacent record.

import GTranslate.Free exposing (..)
import Http


-- Models
type alias Phrase =
    { text : String
    , id : Int
    }

type alias Model =
    { phrases : List Phrase
    , translations : List Translation
    }

init : ( Model, Cmd Msg )
init =
    ( { phrases =
            [ Phrase "Caballo regalado no se le mira el diente." 1
            , Phrase "Al mal tiempo, buena cara." 2
            , Phrase "A falta de pan, buenas son tortas." 3
            , Phrase "Barriga llena, corazón contento." 4
            ]
      , translations = []
      }
    , Cmd.none
    )

-- our configuration record used in the application
customConfig : Config Phrase Msg
customConfig =
    Response
        -- 'Response' is our message
        |> initConfig "en"
        -- specify that english is our target language
        |> withSourceLang "es"
        -- specify that spanish is our source language
        |> withUID (\p -> toString p.id)

-- MESSAGE
type Msg
    = Response (Result Http.Error Translation)
    | Translate
    | Apply

-- UPDATE
update : Msg -> Model -> ( Model, Cmd Msg )
update message model =
    case message of
        Apply ->
            let
                -- The update function used to apply a translation to a phrase
                update =
                    \translation phrase -> { phrase | text = translatedText translation }

                -- Apply the already completed translatations to our list of phrases
                newPhrases =
                    model.phrases |> apply customConfig update model.translations
            in
            -- update our model
            ( { model | phrases = newPhrases }, Cmd.none )

        Translate ->
            -- Translate the all stored phrases
            ( model, batchRecords customConfig (\p -> p.text) model.phrases )

        Response (Ok translation) ->
            -- store our completed translations
            ( { model | translations = translation :: model.translations }, Cmd.none )

        Response (Err msg) ->
            -- handle error here
            ( model, Cmd.none )

Opaque Types


type alias Translation =
Translation

This is the type that is decoded from the JSON from the google translate api. This type contains useful information like: translation, original text, source language, target language, and confidence level.


type alias Config a msg =
Config a msg

This type is used to tell our library how to translate and "tag" each translation. The 'a'in the type signature represents the custom record type than you can optionally provide a function to create a unique ID for each record.

Config Functions

initConfig : String -> (Result Http.Error Translation -> msg) -> Config a msg

This provides a helper function to create a bare bones config object with no uidGenerator or sourceLanguage is specified

withSourceLang : String -> Config a msg -> Config a msg

add/update a source language of a pre-existing Config

withUID : (a -> String) -> Config a msg -> Config a msg

add/update a uid generator function of a pre-existing Config

configSourceLang : Config a msg -> Maybe String

Gets the source language used in this Config

configTargetLang : Config a msg -> String

Gets the target language used in this Config

configMessage : Config a msg -> Result Http.Error Translation -> msg

Gets the custom message used in this Config

configUID : Config a msg -> Maybe (a -> String)

Gets the unique id generator function used in this config record

Translation Functions

translatedText : Translation -> String

Get the translated text from a Translation type

import GTranslate.Free exposing (Translation, translatedText)

Translation "how are you doing?" "¿como estas?" "es" "en" 0.98
    |> translatedText

--> "how are you doing?"

originalText : Translation -> String

Get the original text from a Translation type

import GTranslate.Free exposing (Translation, originalText)

Translation "how are you doing?" "¿como estas?" "es" "en" 0.98
    |> originalText

--> "¿como estas?"

sourceLanguage : Translation -> String

Get the source language from a Translation type

import GTranslate.Free exposing (Translation, sourceLanguage)

Translation "how are you doing?" "¿como estas?" "es" "en" 0.98
    |> sourceLanguage

--> "es"

targetLanguage : Translation -> String

Get the target language from this Translation type

import GTranslate.Free exposing (Translation, targetLanguage)

Translation "how are you doing?" "¿como estas?" "es" "en" 0.98
    |> targetLanguage

--> "en"

id : Translation -> Maybe String

Get the id of this Translation if it exists. The id is optional and must be a string

import GTranslate.Free exposing (Translation, id)

Translation "1" "how are you doing?" "¿como estas?" "es" "en" 0.98 "sample-1"
    |> id

--> "1"

changeID : String -> Translation -> Translation

Convience function to add/overwrite an id on a translation object