# com.innovaphone.translation

This API is used for text translation (HTML payload is also supported) against an external service.

## Messages

Translate
TranslateAll
GetTargetLanguages
DetectLanguage

### Translate

Translate a specific payload to requested language.

    {
        mt:   "Translate",
        html: "Payload we want translated",
        langDst: "de"
    }

#### Parameters

string mt | message type [mandatory]
string html | payload to be translated [mandatory]
string langSrc | 2 letter source language. If not set, the language will be detected. [optional]
string langDst | target language. If not set, the current myApps language will be used. [optional]

If you want to exclude some content from translation, you can wrap them in an HTML tag with the parameter `translate="no"`. (Example: "`Bananas are <span translate="no">yellow</span> fruits.`)

#### Response

    {
        mt:        "TranslateResult",
        html:      "Nutzdaten, die übersetzt werden sollen",
        langSrc:   "en"
        langDst:   "de"
        unchanged: false
    }

#### Parameters

string mt | message type (is "TranslateResult")
string html | translated payload
string langSrc | 2 letter source language
string langDst | target language
bool unchanged | labelling if the payload in html have been changed

#### Error Response

If you run into an error you will receive the following response.

    {
        mt:    "TranslateResult",
        html:  "Error: [English error message which can be shown to the User]",
        error: true
    }

#### Parameters

string mt | message type (is "TranslateResult")
string html | English error message which can be shown to the User
bool error | labelling whether error was send. Only sent if true [optional]

### TranslateAll

Translate a specific payload to all possible languages.

    {
        mt:   "TranslateAll",
        html: "Christmas Tree"
    }

#### Parameters

string mt | message type (is "TranslateAll") [mandatory]
string html | payload to be translated [mandatory]
string langSrc | 2 letter source language [optional]

#### Response

    {
        mt:     "TranslateAllResult",
        html:   [
            { langSrc: "en-gb", langDst: "bg", html: "Коледна елха" },
            { langSrc: "en-gb", langDst: "cs", html: "Vánoční stromek" },
            { langSrc: "en-gb", langDst: "da", html: "Juletræ" },
            { langSrc: "en-gb", langDst: "de", html: "Weihnachtsbaum" },
            { langSrc: "en-gb", langDst: "el", html: "Χριστουγεννιάτικο δέντρο" },
            ...
        ]
    }

#### Parameters

string mt | message type (is "TranslateAllResult")
array html | array of translated payload for all languages

### GetTargetLanguages

Get all possible target languages.

    {
        mt:   "GetTargetLanguages"
    }

#### Parameters

string mt | message type (is "GetTargetLanguages")

#### Response

    {
        mt:        "GetTargetLanguagesResult",
        languages: [
            { language: "bg", name: "Bulgarian" },
            { language: "cs", name: "Czech" },
            { language: "da", name: "Danish" },
            { language: "de", name: "German" },
            { language: "en-gb", name: "English (British)" },
            { language: "en-us", name: "English (American)" },
            { language: "el", name: "Greek" },
            ...
        ]
    }

#### Parameters

string mt | message type (is "GetTargetLanguagesResult")
array languages | array of all supported target languages

### DetectLanguage

Detect langiage from given string.

    {
        mt:   "DetectLanguage",
        html: "Payload that should be detected"
    }

#### Parameters

string mt | message type (is "DetectLanguage")
string html | payload

#### Response

    {
        mt:   "DetectLanguageResult",
        lang: "en-gb"
    }

#### Parameters

string mt | message type (is "DetectLanguageResult")
array lang | detected language, empty if no match
bool error | labelling whether error was send. Only sent if true [optional]

## Example

You can consume the API com.innovaphone.translate and send translation request to them. Inside the callback you can access the translated version via recv.msg.html

    var translateApi = start.consumeApi("com.innovaphone.translate");
    translateApi.sendSrc({ mt: "translate", html: "<div>Hello World!</div>", lang: "de" }, translateApi.providers[0], function (recv) {
        console.log('translated text: '+recv.msg.html);
    });

## More specific language specification than 2-letter langDst

Regional languages have also been supported since 15r1. For example, instead of "en" there is now "en-gb" and "en-us". If the 2-letter specification is set for such languages with regional differences, these are mapped to the most obvious from a European perspective for compatibility reasons

Current Mappins:

    en => en-gb
    pt => pt-pt
    zh => zh-hans