Overview
If you followed the initial steps in our
Quick Start page, feel free to jump over this overview.
If you don't already have an API Key, please follow the instructions on the
Quick Start page or the
Documentation page.
For the examples, we consider the use of the Microsoft .NET Framework 3.5 and the C# language. However, the code logic and the use of the API services can be extrapolated to other languages and technologies. We also assume you were able to create a service reference to the API Web Services. For more information, please view the
Documentation page.
A simple HelloWorld
If you have already experimented the
Hello World section in our
Quick Start page , feel free to skip ahead.
To test the connection to the STREAM API, let's call the
HelloWorld service. This service exists only for connection testing purposes.
...
try
{
//call the HelloWorld method
string resultMessage = YourServiceReference.HelloWorld();
//display the result message in the Output window
System.Diagnostics.Debug.WriteLine(resultMessage);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are sucessfull, you will receive the following message: "Hello World - You are connected to TranslateMedia." If your code is correct and you obtain an error while trying to connect, please make sure your internet connection is working.
Using Authentication
If you have already experimented the
Consuming services that require authentication section in our
Quick Start page , feel free to skip ahead.
Some services require you to authenticate yourself. To test the authentication let's call the
HelloWorldWithAuthentication method. This method exists only for testing purposes.
To provide a secure use of our API, we use a Token based authentication. You will need to authenticate yourself using your account username and API Key. Upon a sucessful authentication, the API will generate and return an Authentication Token that you will use to make all posterior service calls. This Authentication Token has an activity expiration time, in a similar way to a session token.
...
//set up a Authentication Header with you authentication credentials
AuthenticationHeader credentials = new AuthenticationHeader();
credentials.Username = "YourUsername";
credentials.ApiKey = "YourPrivateApiKey";
try
{
//authenticate and obtain the Authentication Token
AuthenticationToken AuthToken = YourServiceReference.Authenticate(credentials);
if (AuthToken.authenticationSuccessful)
{
//call the HelloWorlWithAuthentication method, passing the Authentication Token
string resultMessage = YourServiceReference.HelloWorldWithAuthentication(AuthToken);
//display the result message in the Output window
System.Diagnostics.Debug.WriteLine(resultMessage);
}
else
{
//if the authentication is not successful, display the returned error message in the Output window
System.Diagnostics.Debug.WriteLine(AuthToken.m_errors.description);
}
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
To authenticate and obtain a Token, you must call the Authenticate method, providing your authentication credentials. If the authentication fails, you will receive an error description message that will allow you to know why the authentication failed. You can learn more about the
Authenticate method and possible error messages in the
Documentation page.
If your call to the HelloWorldWithAuthentication method is successful, you will receive the message: "Hello World - You are authenticated and connected to TranslateMedia.".
Obtaining languages and specialities
Several methods of the STREAM API use language and specialism as an input parameter, in the form of an numerical ID, . Therefore, the API contains some methods that allow you to obtain the complete list of available languages and specialities, with their ID's.
The API provides the following methods:
GetLanguagesList ,
GetSpecialitiesList,
GetAvailableSpecialities and
GetAvailableTargetLanguages.
You can learn more about each of these functions on the
Documentation page.
These methods can be used without authentication.
Obtaining a list of supported languages
To obtain a list of suported languages, use the method
GetLanguagesList . The code below is an example of how to call this method.
...
try
{
//call the GetLanguagesList method. This method returns an array of SOAPLanguage objects, which
//represents a language in the STREAM system
SOAPlanguage[] langs = YourServiceReference.GetLanguagesList();
//display the obtained languages in the Output window
foreach (SOAPlanguage lang in langs)
System.Diagnostics.Debug.WriteLine(lang.languageID + " - " + lang.description);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are sucessfull, you will obtain a list of languages. You can learn more about the GetLanguagesList method in our
Documentation page.
Obtaining a list of supported specialities
To obtain a list of suported specialities, use the method
GetSpecialitiesList . The code below is an example of how to call this method.
...
try
{
//call the GetSpecialitiesList method. This method returns an array of SOAPSpeciality objects, which
//represent a speciality in the STREAM system
SOAPspeciality[] specs = YourServiceReference.GetSpecialitiesList();
//display the obtained languages in the Output window
foreach (SOAPspeciality spec in specs)
System.Diagnostics.Debug.WriteLine(spec.specialityID + " - " + spec.description);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are sucessfull, you will obtain a list of specialities. You can learn more about the GetSpecialitiesList method in our
Documentation page.
Obtaining a language ID
Some of the methods provided by the API accept languages parameters, in the form of a numeric ID. The language ID must one the possible values of the
Languages code list .
To facilitate this task, we provide the GetLanguageID method, that will allow you to get the language ID by specifying the language name.
...
try
{
string languageName = "English"; //just as an example
//call the GetLanguageID method. This method returns a SOAPLanguage object
SOAPlanguage language = YourServiceReference.GetLanguageID(languageName);
//display the obtained languages ID the Output window
System.Diagnostics.Debug.WriteLine(language.languageID);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are successful, you will find the language ID in the languageID member of the SOAPlanguage object. If the value of this member is -1, it means that it did not find the language. When no langauge is found, please verify that you specified a correct language and that it is contained in the
Languages code list .
Obtaining a language ID using a RFC 5646 language code
For a more formal specification, we can obtain language ID's using the language RFC 5646 code. This can be done by using the GetLanguageIdRfc5646 method.
...
try
{
string languageCode = "pt-BR"; //just as an example
//call the GetLanguageIdRfc5646 method. This method returns a SOAPLanguage object
SOAPlanguage language = YourServiceReference.GetLanguageIdRfc5646(languageCode);
//display the obtained languages ID the Output window
System.Diagnostics.Debug.WriteLine(language.languageID);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are successful, you will find the language ID in the languageID member of the SOAPlanguage object. If the value of this member is -1, it means that it did not find the language.
Obtaining a list of available specialities
The available specialities depend on the source language. To obtain a list of available specialities for a specific language, use the method
GetAvailableSpecialities . The code below is an example of how to call this method.
...
try
{
//get the language ID for the source language
int languageSourceID = ((SOAPlanguage) YourServiceReference.GetLanguageID("English")).languageID;
//call the GetAvailableSpecialities method. This method returns an array of SOAPSpeciality objects, which
//represent a speciality in the STREAM system
SOAPspeciality[] specs = YourServiceReference.GetAvailableSpecialities(languageSourceID);
//display the available specialities in the Output window
foreach (SOAPspeciality spec in specs)
System.Diagnostics.Debug.WriteLine(spec.specialityID + " - " + spec.description);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are sucessfull, you will obtain a list of specialities. You can learn more about the GetAvailableSpecialities method in our
Documentation page.
Obtaining a list of available target languages
The available target languages refers to the language you wish to translate to. Their availability depends on the source language and a speciality. To obtain a list of available target languages for a specific language and speciality, use the method
GetAvailableTargetLanguages . The code below is an example of how to call this method.
...
try
{
//get the language ID for the source language
int languageSourceID = ((SOAPlanguage) YourServiceReference.GetLanguageID("English")).languageID;
int specialityID = 16; // General (consult the specialities code list)
//call the GetTargetLanguages method. This method returns an array of SOAPSpeciality objects, which
//represent a speciality in the STREAM system
SOAPlanguage[] languages = YourServiceReference.GetAvailableTargetLanguages(languageSourceID, specialityID);
//display the available specialities in the Output window
foreach (SOAPlanguage lang in languages)
System.Diagnostics.Debug.WriteLine(lang.languageID + " - " + lang.description);
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
If you are sucessfull, you will obtain a list of specialities. You can learn more about the GetAvailableSpecialities method in our
Documentation page.
Obtaining quotes
In order to order a translation using the STREAM API you need to obtain a quote. The STREAM API contains several functions to obtain a quote for a translation service, based on input parameters like: source and target languages, speciality, plain text or several other formats of source document, authenticity certification and some others advanced user settings.
Obtaining a quote
One of the most simple quotation methods is the
GetQuoteForPlainText. This method allows you to pass a piece of text to be quoted. The code below is an example of how to call this method.
...
try
{
//get the language ID for the source language
int languageSourceID = ((SOAPlanguage)YourServiceReference.GetLanguageID("English")).languageID;
int specialityID = 16; // General (consult the specialities code list)
//to keep the example simple, we are not checking if this is a available target language considering
//the source language and the speciality
int[] languageTargetID = { ((SOAPlanguage)YourServiceReference.GetLanguageID("French")).languageID };
//the plain text to translate
string plainText = "The quick brown fox jumps over the lazy dog";
//call the GetQuoteForPlainText method. This method returns a SOAPreponse object
SOAPresponse response = (SOAPresponse)YourServiceReference.GetQuoteForPlainText(AuthToken,
languageSourceID, specialityID, languageTargetID, plainText);
//check if there was an error during the quote calculation process
if (response.m_errors.errorPresent == true)
{
System.Diagnostics.Debug.WriteLine(response.m_errors.errorCode + response.m_errors.description);
}
else
{
//display the quotes in the Output window
foreach (SOAPquote quote in response.m_quotes)
{
System.Diagnostics.Debug.WriteLine("Quote ID: " + quote.idQuote +
"Quote price: " + quote.dQuotePrice + quote.sCurrency +
" Estimate: " + quote.dtTargetCompletion + " type? "
+ quote.byType + " Execution type(min): "
+ quote.iMinutesElapsed);
}
}
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
The function returns a SOAPresponse object. If no error occurs, the m_quotes member will contain an array with the quotes. If an error ocurred, the errorPresent property in the m_errors member will be true, as can be seen in the example.
You can learn more about the GetQuoteForPlainText method in our
Documentation page.
Requesting a translation
After obtaining the quotation for a translation service, you can order the translation. This step, in its simplest form, consists basically in calling the CreateOrder method, passing the ID of the quote that you desire.
Create an order
Let's use the
CreateOrder method to order a translation, based in a quote ID.
...
try
{
//this is just an example
int selectedQuote = 65401;
SOAPresponse response = YourServiceReference.CreateOrder(AuthToken, selectedQuote);
//check if there was an error during the ordering process
if (response.m_errors.errorPresent == true)
{
System.Diagnostics.Debug.WriteLine(response.m_errors.errorCode + response.m_errors.description);
}
else
{
System.Diagnostics.Debug.WriteLine("Ordered with success");
}
}
catch (Exception ex)
{
//if an error occurs, display the error message in the Output window
System.Diagnostics.Debug.WriteLine(ex.Message);
}
...
The function returns a SOAPresponse object. If no error occurs, the m_quotes member will contain an array with the quotes. If an error ocurred, the errorPresent property in the m_errors member will be true, as can be seen in the example.
You can learn more about the GetQuoteForPlainText method in our
Documentation page.
