==============================================
   Microsoft Translator script for Asterisk
==============================================

This script makes use of Microsoft Translator to translate
text strings and return them as channel variables.

------------
Requirements
------------
Perl         The Perl Programming Language
perl-libwww  The World-Wide Web library for Perl
perl-Crypt-SSLeay or perl-IO-Socket-SSL for use of SSL/TLS encryption
Internet access in order to contact MS and get the language data.

To use this script you have to subscribe to the Microsoft Translator API on Azure Marketplace:
https://datamarket.azure.com/developer/applications/
and register your application with Azure DataMarket:
https://datamarket.azure.com/developer/applications/

------------
Installation
------------
To install copy mstrasnlate.agi to your agi-bin directory.
Usually this is /var/lib/asterisk/agi-bin/
To make sure check your /etc/asterisk/asterisk.conf file

-----
Usage
-----
agi(mstranslate.agi,"text",[target language],[source language]):
 The text string will be send to MS Translator for translation to target language.
 The translated text will be stored as a channel variable named 'mstranslation'.
 The setting of source language is optional, if not set the tranlator engine
 will try to auto detect it.
 If both target language and source language are omitted the script performs language
 detection on the given text string and returns the two-character language code
 as the value of the channel variable 'mslang'

--------
Examples
--------
sample dialplan code for your extensions.conf

;Translate a text string from english to french:
exten => 1234,1,agi(mstranslate.agi,"This is some random text.",fr)
exten => 1234,n,Verbose(1,Translated text: ${mstranslation})

;Translate from greek to german:
exten => 1234,1,agi(mstranslate.agi,"Αυτό είναι ένα απλό τέστ στα ελληνικά.",de)
exten => 1234,n,Verbose(1,Translated text: ${mstranslation})

;Translate from japanese to english:
exten => 1234,1,agi(mstranslate.agi,"これは、日本の簡単なテストです。良い一日を。",en)
exten => 1234,n,Verbose(1,Translated text: ${mstranslation})

;Translate string to many languages:
exten => 1235,1,Set(MYTEXT="This is some random text for translation.")
exten => 1235,n,agi(mstranslate.agi,"${MYTEXT}",it)
exten => 1235,n,Verbose(1,In Italian: ${mstranslation})

exten => 1235,n,agi(mstranslate.agi,"${MYTEXT}",fr)
exten => 1235,n,Verbose(1,In French: ${mstranslation})

exten => 1235,n,agi(mstranslate.agi,"${MYTEXT}",ja)
exten => 1235,n,Verbose(1,In Japanese: ${mstranslation})

exten => 1235,n,agi(mstranslate.agi,"${MYTEXT}",es)
exten => 1235,n,Verbose(1,In Spanish: ${mstranslation})

;Detect text language:
exten => 1236,1,Set(MYTEXT="This is some random text for detection.")
exten => 1236,n,agi(mstranslate.agi,"${MYTEXT}")
exten => 1236,n,Verbose(1,Detected language: ${mslang})


-------------------
Supported Languages
-------------------
Translation is possible between any two of these languages:
ar		bg		ca
zh-CHS		zh-CHT
cs		da		nl
en		et		fi
fr		de		el
ht		he		hi
mww		hu		id
it		ja		ko
lv		lt		no
pl		pt		ro
ru		sk		sl
es		sv		th
tr		uk		vi

-----------------------
Security Considerations
-----------------------
This script contacts MS servers in order to get language and text data.
The script uses TLS to encrypt all the traffic between your pbx and MS servers
so no 3rd party can eavesdrop your communication.

-------
License
-------
The MStranslate script for asterisk is distributed under the GNU General Public
License v2. See COPYING for details.

--------
Homepage
--------
http://zaf.github.com/asterisk-mstranslate/

---------------
API Description
---------------

Text Translation:

Request
-------
GET    http://api.microsofttranslator.com/V2/Http.svc/Translate

Parameters
----------
appId
 Required. If the Authorization header is used, leave the appid field empty else a string
 containing "Bearer" + " " + access token.

text
 Required. A string representing the text to translate.

from
 Optional. A string representing the language code of the translation text.

to
 Required. A string representing the language code to translate the text into.

contentType
 Required. The format of the text being translated. The supported formats are "text/plain"
 and "text/html". Any HTML needs to be well-formed.

category
 Optional. The category of the text to translate. The only supported category is "general".

Response
--------
A string representing the translated text.


Language Detection:

Request
-------
GET    http://api.microsofttranslator.com/V2/Http.svc/Detect

Parameters
----------
appId
 Required. If the Authorization header is used, leave the appid field empty else a string
 containing "Bearer" + " " + access token.

text
 Required. A string containing some text whose language is to be identified.

Response
--------
A string containing a two-character Language code for the given text.