Package com.adobe.granite.translation.api

Interface TranslationService

  • All Known Implementing Classes:
    AbstractTranslationService
    @ProviderType
public interface TranslationService
    The TranslationService interface provides a single source for all translation functionality. It is made up of two parts. The (1.0) API provides synchronous machine translation based functionality. The (2.0) API now also provides asynchronous translation functionality to serve a wider range of project based needs.

    The (1.0) API legacy translation interface provides functionality for synchronous translation, language detection, and Translation Memory (TM) Updates. This interface is implemented by Translation Connectors to provide connectivity to external MT engines. The Connectors contain the engine specific logic to authenticate against and call their respective MT engines.

    The 1.0 synchronous service is implemented in three parts.

    Helper methods that make Machine Translation Possible

    • isServiceAvailable: check if a Machine Translation Service is connected and available for use.
    • isDirectionSupported: check if a Machine Translation Service can translate between a particular source and target pair in that direction.
    • detectLanguage: determine the language identity (French, German, etc.) of a source string.

    Translation methods that do the actual translation

    • translateString: translate a single string from source language into target language
    • translateArray: translate an array of strings from one source language into one target language

    Storage and Retrieval methods that store translation with an MT provider and retrieve those translations.

    • getStoredTranslations: send a source string for translation and retrieve existing ranked translations for that source string.
    • addStoredTranslation: push an target translation for a particular source string into a services storage repository. (string and array versions)

    The 2.0 asynchronous service is implemented in 3 parts.

    Translation Content that provides objects for translation and supporting that translation

    • uploadTranslationObject: Upload a unique Translation Object (TO) for translation.
    • getTranslatedObject: Download (Returns input stream of the now translated) TO.
    • getTranslationObjectStatus: Used to inquire on the current STATUS of a TO.
    • getTranslationObjectsStatus: Used to inquire on the current STATUS of a set of TOs.
    • updateTranslationObjectState: Change the STATE of a TO to direct it through the translation process.
    • updateTranslationObjectsState: Change the STATE of multiple TOs to direct them through the translation process.

    Translation Packaging that provides containers for organizing and delivering objects for translation.

    • createTranslationJob: Create a new Translation Job (TJ) for a set of Translation Objects.
    • getFinalScope: Returns the SCOPE (word count, size, etc.) of a SUBMITTED TJ
    • updateTranslationJobMetadata Modify Metadata attached to a Translation Job (TJ)
    • updateTranslationJobState: Modify the STATE of a Translation Job (TJ)

    Translation Communication that provides tools for using comments and metadata with the objects and job.

    • addTranslationJobComment: Add a new comment to a translation job.
    • addTranslationObjectComment: Add a new comment to a translation object.
    • getTranslationJobCommentCollection: Used to gather all the comments attached to a particular TJ.
    • : Used to return the current STATUS of a particular TJ.
    • getTranslationObjectCommentCollection: Used to gather the comments attached to a particular TO.

    • Method Detail

      • supportedLanguages

        java.util.Map<java.lang.String,​java.lang.String> supportedLanguages()
        Returns the full list of supported language codes for this service. This is a comprehensive list of all supported languages. Use supportedLanguages to determine which languages are supported by a TranslationService. It returns a human readable name for the languages as well a language code for those languages. The service has the capability to recognize these codes and the language named. These are the languages which detectLanguage can recognize. It doesn't not necessarily mean the service can translate between all these languages. Use isDirectionSupported (see below) to retrieve the subset of direction pairs.
        Returns:
        Map<String, String> containing the full list of supported languages and their English names.

      • isDirectionSupported

        boolean isDirectionSupported​(java.lang.String sourceLanguage,
                             java.lang.String targetLanguage)
                      throws TranslationException
        Returns true/false whether the current service supports the specified translation direction. At it's simplest a translation service consists of a language pair and a direction. A language pair is any two languages. For example: French and English. A direction is which language is the Source language and which language is the Target language. For example: I want to translate from English to French, so English would be the Source and French would be the Target. If the service supports translation from English to French that would be one direction that was supported. Similarly if the service supports translation from French to English that would be another direction. Use isDirectionSupported to learn if the required language pair and direction is available.
        Parameters:
        sourceLanguage - The language code to be translated from
        targetLanguage - The language code to be translated to
        Returns:
        Returns true if engine supports direction, false otherwise
        Throws:
        TranslationException - the translation exception

      • detectLanguage

        java.lang.String detectLanguage​(java.lang.String detectSource,
                                TranslationConstants.ContentType contentType)
                         throws TranslationException
        Detects the language of the passed in String (accepts both PLAIN and HTML text). Use to determine the language of piece of content. For example: A forum user comments on a discussion thread in their native script. The forum administrator would like to provide a translation of this comment for all the users, but doesn't recognize the language it was posted in. The method detectLanguage makes known the language ID of the comment in question so it may be translated.
        Parameters:
        detectSource - The content to determine the language of
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        Returns:
        Returns the language code of the passed in string (language or locale (if known)) Returns "UNKNOWN" if language cannot be determined (@see TranslationException .ErrorCodes#UNKNOWN_LANGUAGE)
        Throws:
        TranslationException - the translation exception

      • translateString

        TranslationResult translateString​(java.lang.String sourceString,
                                  java.lang.String sourceLanguage,
                                  java.lang.String targetLanguage,
                                  TranslationConstants.ContentType contentType,
                                  java.lang.String contentCategory)
                           throws TranslationException
        Translates a given String and returns the best fit (highest rated) translation. The connector may determine a specific engine to use based on the input parameters. This is the core of the translation API. A user calls the translateString method to send a Source string for translation. The translation (the Target String) is then returned to the user.
        Parameters:
        sourceString - The string to be translated
        sourceLanguage - (optional) The string representing the FROM language code. This allows a NULL value to be passed. If NULL, the source language is determined by leveraging the "detectLanguage" function. A TranslationException with ErrorCode UNKNOWN_LANGUAGE will be thrown if it cannot be determined.
        targetLanguage - The string representing the TO language code.
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        contentCategory - (optional) The content category of the source (@see TranslationConstants.Categories) This will use the default value if NULL or blank is passed.
        Returns:
        A translation of the "sourceString" String in the "targetLanguage" (best match)
        Throws:
        TranslationException - the translation exception

      • translateArray

        TranslationResult[] translateArray​(java.lang.String[] sourceStringArr,
                                   java.lang.String sourceLanguage,
                                   java.lang.String targetLanguage,
                                   TranslationConstants.ContentType contentType,
                                   java.lang.String contentCategory)
                            throws TranslationException
        Translates all strings in a given String Array and returns the best fit (highest rated) translations. The connector may determine a specific engine to use based on the input parameters. This function only allows one direction (TO/FROM pair). This method is like translateString with one difference. The translateArray method sends an Array of strings out for translation at the same time. Translations are returned for each string in the array. This allows the user to batch process strings for translation.
        Parameters:
        sourceStringArr - An Array of Strings to be translated
        sourceLanguage - (optional) The string representing the FROM language code. This allows a NULL value to be passed. If NULL, the source language is determined by leveraging the "detectLanguage" function. A TranslationException with ErrorCode UNKNOWN_LANGUAGE will be thrown if it cannot be determined. NOTE: Only the first array position will be used to determine a NULL or blank FROM value.
        targetLanguage - The string representing the TO language code.
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        contentCategory - (optional) The content category of the source (@see TranslationConstants.Categories) This will use the default value if NULL or blank is passed.
        Returns:
        An array of TranslationReturnObjects in the same order as the sourceStringArr
        Throws:
        TranslationException - the translation exception

      • getAllStoredTranslations

        TranslationResult[] getAllStoredTranslations​(java.lang.String sourceString,
                                             java.lang.String sourceLanguage,
                                             java.lang.String targetLanguage,
                                             TranslationConstants.ContentType contentType,
                                             java.lang.String contentCategory,
                                             java.lang.String userId,
                                             int maxTranslations)
                                      throws TranslationException
        Returns all available translation responses for a given string, array will be sorted by rating (best fit first, in "0"). This function is only available if this connector leverages a Translation Memory system. Use getAllStoredTranslations when the user would like to retrieve not only the highest ranked Machine Translated options but also any other alternate translations as they are ranked. These stored Translation Memory options are rated by the admin/moderator. This permits service admin/moderator to better control the translations returned by the Machine Translation Service. It also may be used to support the moderation of crowd sourced and edited translations.
        Parameters:
        sourceString - The string to be translated
        sourceLanguage - (optional) The string representing the FROM language code. This allows a NULL value to be passed. If NULL, the source language is determined by leveraging the "detectLanguage" function. A TranslationException with ErrorCode UNKNOWN_LANGUAGE will be thrown if it cannot be determined.
        targetLanguage - The string representing the TO language code.
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        contentCategory - (optional) The content category of the source (@see TranslationConstants.Categories) This will use the default value if NULL or blank is passed.
        userId - (optional) filters the results specific to a passed in User
        maxTranslations - (optional) Specifies the maximum number of translation response Strings in array. If not specified ALL available translations will be returned.
        Returns:
        an array of TranslationResult objects which contain all translations stored in the Machine Translation store
        Throws:
        TranslationException - the translation exception

      • storeTranslation

        void storeTranslation​(java.lang.String originalText,
                      java.lang.String sourceLanguage,
                      java.lang.String targetLanguage,
                      java.lang.String updatedTranslation,
                      TranslationConstants.ContentType contentType,
                      java.lang.String contentCategory,
                      java.lang.String userId,
                      int rating,
                      java.lang.String path)
               throws TranslationException
        Updates a translation in the Translation Memory engine. Use storeTranslation when an admin/moderator would like to push a reviewed translation into Translation Memory for future use. This API is used for overwriting to the MT service. Stored Translations are added to Translation Memory with a confidence rating. If there is an exact match with a stored translation the translation with the highest confidence level rating will be returned. The default score for translation quality in the TIF (Translation Integration Framework) is fixed at "0" on a scale from "-n" to "+n". To work with the different scales of external services "-n" and "+n" can represent any value range (i.e. -100 .. +100). Individual connectors for each translation service (synchronous or asynchronous) handle conversions between this scale and the scale used by the service being called.
        Parameters:
        originalText - The string that was originally translated. This can be only one sentence.
        sourceLanguage - The string representing the locale that was translated from (source) This accepts all acceptable locale strings (2 and 5 char versions) Example: en, en_us, en-us, en_US
        targetLanguage - The string representing the locale that was translated to (destination) This accepts all acceptable locale strings (2 and 5 char versions) Example: en, en_us, en-us, en_US
        updatedTranslation - The string representing the updated text after an editor reviewed and modified
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        contentCategory - (optional) The Content Category @see TranslationConstants.Categories
        userId - The user who modified the translation
        rating - (optional) A number representing the "quality" rating of the new translation. The scale is from -n .. +n with 0 being the default setting for translation quality.
        path - (optional) Path to the node containing the translated content
        Throws:
        TranslationException - the translation exception

      • storeTranslation

        void storeTranslation​(java.lang.String[] originalText,
                      java.lang.String sourceLanguage,
                      java.lang.String targetLanguage,
                      java.lang.String[] updatedTranslation,
                      TranslationConstants.ContentType contentType,
                      java.lang.String contentCategory,
                      java.lang.String userId,
                      int rating,
                      java.lang.String path)
               throws TranslationException
        Updates an array of translations in the Translation Memory engine. Use storeTranslation when an admin/moderator would like to push a reviewed translation into Translation Memory for future use. This API is used for overwriting to the MT service. Stored Translations are added to Translation Memory with a confidence rating. If there is an exact match with a stored translation the translation with the highest confidence level rating will be returned. The default score for translation quality in the TIF (Translation Integration Framework) is fixed at "0" on a scale from "-n" to "+n". To work with the different scales of external services "-n" and "+n" can represent any value range (i.e. -100 .. +100). Individual connectors for each translation service (synchronous or asynchronous) handle conversions between this scale and the scale used by the service being called.
        Parameters:
        originalText - An array of the original text that was translated
        sourceLanguage - The string representing the locale that was translated from (source) This accepts all acceptable locale strings (2 and 5 char versions) Example: en, en_us, en-us, en_US
        targetLanguage - The string representing the locale that was translated to (destination) This accepts all acceptable locale strings (2 and 5 char versions) Example: en, en_us, en-us, en_US
        updatedTranslation - An array of strings containing the updated translations, this must be in the same order as the originalText array (originalText[1] is the original text of translated string updatedTranslation[1]). Thus originalText .length must == updatedTranslation.length or an exception will be thrown.
        contentType - The content type of the source (@see TranslationConstants.ContentTypes)
        contentCategory - (optional) The Content Category @see TranslationConstants.Categories
        userId - The user who modified the translation
        rating - (optional) A number representing the "quality" rating of the new translation. The scale is from -n .. +n with 0 being the default setting for translation quality.
        path - (optional) Path to the node containing the translated content
        Throws:
        TranslationException - the translation exception

      • getDefaultCategory

        java.lang.String getDefaultCategory()
        Gets the default category.
        Returns:
        Returns a the configured Default Category for this TranslationService instance

      • setDefaultCategory

        void setDefaultCategory​(java.lang.String defaultCategory)
        Sets the default category.
        Parameters:
        defaultCategory - The string representing the category which will be set as the default. This is the value the TranslationService will use if no category is specified elsewhere.

      • getTranslationServiceInfo

        TranslationService.TranslationServiceInfo getTranslationServiceInfo()
        Gets information on a translation service.
        Returns:
        Returns a TranslationInfo object which contains the Name, Label, and Attribution Strings for this specific TranslationService implementation

      • createTranslationJob

        java.lang.String createTranslationJob​(java.lang.String name,
                                      java.lang.String description,
                                      java.lang.String strSourceLanguage,
                                      java.lang.String strTargetLanguage,
                                      java.util.Date dueDate,
                                      TranslationState state,
                                      TranslationMetadata jobMetadata)
                               throws TranslationException
        Is the core method of TranslationService Class for Asynchronous translation. Implementation creates the Translation Job at the translation requester's end of the connector. The Translation Job is the top level container to hold unique Translation Objects, their metadata, and to track the status of the Objects during translation. Each language in a translation process is given a unique translation job per language. The Translation Service monitors the STATUS of Translation Objects between the Translation Job Container with the translation requester and a paired copy of it with the external translation service.
        Parameters:
        name - of translation job
        description - description
        strTargetLanguage - the target language into which a project will be translated
        strSourceLanguage - source language of the Translation Job.
        dueDate - due date when this Translation Job need to be translated
        state - current state of translation job
        jobMetadata - metadata for translation job
        Returns:
        id, This should return unique translation job id, which can identify the job at connector end.
        Throws:
        TranslationException - the translation exception

      • updateTranslationJobMetadata

        void updateTranslationJobMetadata​(java.lang.String strTranslationJobID,
                                  TranslationMetadata jobMetadata,
                                  TranslationConstants.TranslationMethod translationMethod)
                           throws TranslationException
        Update translation job metadata.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        jobMetadata - metadata for translation job
        translationMethod - translation Method
        Throws:
        TranslationException - the translation exception

      • uploadTranslationObject

        java.lang.String uploadTranslationObject​(java.lang.String strTranslationJobID,
                                         TranslationObject translationObject)
                                  throws TranslationException
        Uploads the Translation Object to the Translation Service Provider. This method is used to uploads the unique Object which needs to be translated.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObject - the unique thing to be translated
        Returns:
        translation Object id, this should be unique Object id for a given Translation Job. this way it can be tracked per Translation Job.
        Throws:
        TranslationException - the translation exception

      • getFinalScope

        TranslationScope getFinalScope​(java.lang.String strTranslationJobID)
                        throws TranslationException
        Gets the final scope for a Translation Job.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        Returns:
        TranslationScope, if all calculation is done return the final scope. Returns null in case final scope calculation is not done.
        Throws:
        TranslationException

      • updateTranslationJobState

        TranslationConstants.TranslationStatus updateTranslationJobState​(java.lang.String strTranslationJobID,
                                                                 TranslationState state)
                                                          throws TranslationException
        Update the Translation Job state. Is used to modify the state of the Translation Job. This allows the user to both GET and SET the Status and Comments attached to a Translation Job
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        state - the state
        Returns:
        the translation status which is an update of the project status
        Throws:
        TranslationException - the translation exception

      • getTranslationJobCommentCollection

        CommentCollection<Comment> getTranslationJobCommentCollection​(java.lang.String strTranslationJobID)
                                                       throws TranslationException
        Gets the Translation Job comment collection. Return all the comments added at Translation Job level. AEM code will check for comment date, author, text to find out if the comment is already part of Collection or not. if it is not present then the comment will be added in collection. this is used to sync comments from connector back to AEM
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        Returns:
        the Translation Job comment collection
        Throws:
        TranslationException

      • addTranslationJobComment

        void addTranslationJobComment​(java.lang.String strTranslationJobID,
                              Comment comment)
                       throws TranslationException
        Adds a comment at the translation job level. Translation Job level Comments are metadata about a particular TJ. They are used to communicate between the Translation Requester and the Translation Service Provider about the Translation Job while translation is is process.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        comment - , Comments attached to the translation Object, a form of Object metadata
        Throws:
        TranslationException - the translation exception

      • getTranslatedObject

        java.io.InputStream getTranslatedObject​(java.lang.String strTranslationJobID,
                                        TranslationObject translationObject)
                                 throws TranslationException
        Gets the translated Object content input stream. This is the step by which Translated Objects are downloaded from the External Translation Service's container back to the Translation Requesters container. This step is carried out after the STATUS' of all Translation Objects is found to be TRANSLATED.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObject - The translation Object
        Returns:
        the translated Object as inputstream
        Throws:
        TranslationException - the translation exception

      • updateTranslationObjectState

        TranslationConstants.TranslationStatus updateTranslationObjectState​(java.lang.String strTranslationJobID,
                                                                    TranslationObject translationObject,
                                                                    TranslationState state)
                                                             throws TranslationException
        Allows the user to update the state for a unique Translation Object. Each Translation Object has a state DRAFT, SUBMITTED, TRANSLATED, etc. The state of each object is used to indicate where it is in the translation process and to move it through the steps of the process. For example: when the Translation Service can query all the Translation Objects in a job and determines that all their status's are now: TRANSLATED then the Translation Service can determine that the Translation Job is now finished. See translation Constants for a list of status
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObject - The translation Object
        state - the state
        Returns:
        the translation status
        Throws:
        TranslationException - the translation exception

      • updateTranslationObjectsState

        TranslationConstants.TranslationStatus[] updateTranslationObjectsState​(java.lang.String strTranslationJobID,
                                                                       TranslationObject[] translationObjects,
                                                                       TranslationState[] states)
                                                                throws TranslationException
        Update the state for an array of translation Objects. This is a batch operation to update the states for multiple translation Objects with a single call. The call returns a list of status states for each translation Object in the order they are stored. See translationConstants for list of states
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObjects - array of translation objects
        states - the states
        Returns:
        the translation status[]
        Throws:
        TranslationException - the translation exception

      • getTranslationObjectsStatus

        TranslationConstants.TranslationStatus[] getTranslationObjectsStatus​(java.lang.String strTranslationJobID,
                                                                     TranslationObject[] translationObjects)
                                                              throws TranslationException
        Gets the status of the translation Object. This can be used for batch operations where you can pass multiple translation Objects as parts of a single Translation Job. In this batch operation the status for each translation Object will be returned in the order they were submitted.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObjects - array of translation objects
        Returns:
        the list of status
        Throws:
        TranslationException - the translation exception

      • getTranslationObjectCommentCollection

        CommentCollection<Comment> getTranslationObjectCommentCollection​(java.lang.String strTranslationJobID,
                                                                 TranslationObject translationObject)
                                                          throws TranslationException
        Gets the Translation Object comment collection. The method will return all the comments added at the translation Object level. The Adobe Experience Manager core code then will check a Translation Object for comments, date information, author attribution or text to find out if this data is already associated with the translation Object. If it is not present then the comment will be added to the translation Object. This method is used to sync comments via the connector back to the AEM Translation Job.
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObject - The translation Object
        Returns:
        the Translation Job comment collection
        Throws:
        TranslationException

      • addTranslationObjectComment

        void addTranslationObjectComment​(java.lang.String strTranslationJobID,
                                 TranslationObject translationObject,
                                 Comment comment)
                          throws TranslationException
        Adds a Comment to the Translation Object. This is used to for communication between the Translation Requester and the Translation Service Provider
        Parameters:
        strTranslationJobID - job id, which was returned on translation job creation
        translationObject - The translation Object
        comment - , Comments attached to the translation Object, a form of Object metadata
        Throws:
        TranslationException - the translation exception

      • updateDueDate

        void updateDueDate​(java.lang.String strTranslationJobID,
                   java.util.Date date)
            throws TranslationException
        Update translation job due-date
        Parameters:
        strTranslationJobID - Translation Job ID
        date - Due date
        Throws:
        TranslationException