# translation

ITranslation is a simple translation client which can use different Translation Services Translation Service.

## File information

File | common/interface/translation.h
Functions | Functions to initialize
Classes | ITranslation UTranslation
Examples | Code Example

# Functions

## Functions to initialize

    extern "C" ITranslation * CreateIBMTranslation(class IIoMux* const iomux,
        class ISocketProvider* const tcpSocketProvider,
        class ISocketProvider* const tlsSocketProvider,
        class ISocketContext* socketContext,
        class UTranslation* const user,
        class IInstanceLog* const log,
        const char* endpoint_url,
        const char* resource_name,
        const char* api_key);

CreateIBMTranslation
  Create an ITranslation instance.

  #### Parameters

  IIoMux * const iomux | The iomux instance needed for socket communication.
  ISocketProvider * const tcpSocketProvider | A socket provider to create a TCP socket.
  ISocketProvider * const tlsSocketProvider | A socket provider to create a TLS socket.
  ISocketContext * const socketContext | An optional socketContext which can be used for the socket which is created by the httpclient. You can disable sending of a client certificate with this socketContext or send a specific own client certificate.
  UTranslation * const user | An UTranslation instance to receive the callbakcs from ITranslation.
  IInstanceLog * const log | The log instance for logging.
  const char* endpoint_url | The URL of the IBM Server for the requests.
  const char* resource_name | The Resource on the IBM Server for the request.
  const char* api_key | The API Key to access the translation service.

  #### Return Value

  The ITranslation instance created. Must be deleted if no longer used.

# Classes

## ITranslation

    class ITranslation {
    public:
        virtual ~ITranslation() {};
        virtual void Translate(class TranslationObject* translationObject) = 0;
        virtual void Shutdown() = 0;
    };

This is the main class of the Translation module. The translation-module is using an external webservice from IBM to translate the texts. Therefore it requires informations from the IBM Cloud Language Translator (IBM Watson Translator).

### Public functions

Translate
  Translate the given text to the given language. For supported languages have a look to the IBM documentation.

  #### Parameters

  class TranslationObject* translationObject | The translation object, which should be translated.

  #### Callbacks

  UTranslation::TranslationCompleted(const char* translation) will be called after the data has been translated.

  #### Remarks

  There should be only one translation requested at a time. It's not supported to translate two texts with the same instance on the same time.

## UTranslation

    class UTranslation {
    public:
        virtual void TranslationConnected(const ITranslation* translator) = 0;
        virtual void TranslationCompleted(const ITranslation* translator, class TranslationObject* translationObject) = 0;
        virtual void TranslationShutdown(const ITranslation* translator) = 0;
        ~UTranslation() {}
    };

This class is for receiving callbacks from the ITranslation. You must pass as subclass of UTranslation to an ITranslation as user.

TranslationCompleted
  Will be called after the translation has been completed.

  #### Parameters

  ITranslation * const httpClient | The calling ITranslation instance.
  class TranslationObject* translationObject | The translation object with the translated text

TranslationShutdown
  Will be called after the translation has been closed.

  #### Parameters

  ITranslation * const httpClient | The calling ITranslation instance.

## TranslationObject

    class TranslationObject : public istd::listElement {
    public:
        const char* getSource_Language() { return source_language; };
        const char* getTarget_Language() { return target_language; };
        const char* getTranslation() { return translation; };
        TranslationObject(const char* text, const char* source_language, const char* target_language);
        ~TranslationObject();
    };

This class is for creating an Object which handles the translation
TranslationObject
  Constructor for a translation object.

  #### Parameters

  const char* text | The text, which should be translated.
  const char* source_language | The source language
  const char* target_language | The target language

getSource_Language
  Readout the source language.

  #### Return Value

  Returns the target language.
getTarget_Language
  Readout the target language.

  #### Return Value

  Returns the target language.
getTranslation
  Readout the Translation.

  #### Return Value

  Returns the translated text.

# Code Example

    app::app(IIoMux * iomux)
        : iomux(iomux)
    {
        // you can optionally create a socketContext, if you e.g. want to disable sending of a client certificate
        class ISocketContext * socketContext = aTlsSocketProvider->CreateSocketContext(this);
        socketContext->DisableClientCertificate();
        // create the translation instance
        this->translation = ITranslation::Create(iomux, service->tcpSocketProvider, service->tlsSocketProvider, socketContext, this, this, "https://api.eu-gb.language-translator.watson.cloud.ibm.com", "/instances/*****************", "******************");
        this->translation->Translate(new class TranslationObject("Hallo Welt", "de", "en"));
    }

    void STT::TranslationCompleted(const ITranslation* translator, const char* translation) {
        printf("Translation: %s", translation);
        this->translation->Shutdown();
    }

    void app::TranslationShutdown(const ITranslation* translator)
    {
        delete this->translation;
    }