Common Operations

The common operations are performed using the default setup:

  • Cloud product using the Europe region
  • API credentials loaded from environment variables
  • Default retry mechanism (retry up to 3 times, with a delay of 5 seconds)
Note

In order to switch the product to Edge, this must be set either on the ClientConfiguration or by using an environment variable as described in Switch between Products section.

Get all Language Pairs

By using the getLanguagePairs method from LanguageWeaverClient, the list of available language pairs will be returned, corresponding to the given client identifier. These will be used for translation requests.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        final LanguagePairsResult languagePairsResult = lwClient.getLanguagePairs();
        // handle result
    }

See the complete sample on Github.

The LanguagePairsResult object contains the following information:

Name Type Description
languagePairs array Contains a list of LanguagePair objects

The LanguagePair object contains the following information:

Name Type Description
name string Language pair name
sourceLanguageId string Three letters language code of the source language
targetLanguageId string Three letters language code of the target language
model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)

For more information about the API, access: Get all Language Pairs.

Get all Linguistic Options for a Language Pair

By using the getLinguisticOptions method from LanguageWeaverClient, the list of available linguistic options of a specific language pair will be returned, corresponding to the given client identifier. These will be used for translation requests.

        try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
            GetLinguisticOptionsRequest getLinguisticOptionsRequest = new GetLinguisticOptionsRequest()
                .setSourceLanguageId("chi")
                .setTargetLanguageId("eng")
                .setModel("generic");

            final LinguisticOptionsResult linguisticOptionsResult = lwClient.getLinguisticOptions(getLinguisticOptionsRequest);
            // handle result
}

See the complete sample on GitHub.

The GetLinguisticOptionsRequest object contains the following information:

Name Type Mandatory Default value Description
sourceLanguageId string yes Three letters language code of the source language
targetLanguageId string yes Three letters language code of the target language
model string yes A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)

The GetLinguisticOptionsRequest object can be obtained from an existing LanguagePair object as well using the toGetLinguisticOptionsRequest() method:

GetLinguisticOptionsRequest getLinguisticOptionsRequest = languagePair.toGetLinguisticOptionsRequest();

The LinguisticOptionsResult object contains the following information:

Name Type Description
linguisticOptions LinguisticOption array List of linguistic options available for the requested language pair

The LinguisticOption object contains the following information:

Name Type Description
id string Linguistic option identifier
systemDefault string System default linguistic option
values string array Available values for the current linguistic option

For more information about the API, access: Get all Linguistic Options for a language pair.

Get all Dictionaries

By using the getDictionaries method from LanguageWeaverClient, the list of available dictionaries will be returned, corresponding to the given client identifier. These can be used for translation requests.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        final DictionariesResult dictionariesResult = lwClient.getDictionaries(1);
        // handle result
    }

See the complete sample on Github.

The getDictionaries method has the following parameters:

Name Type Mandatory Default Description
pageNumber number yes Number specifying the requested page number
pageSize number no 100 Number specifying the requested page size

The DictionariesResult object contains the following information:

Name Type Description
dictionaries array Contains a list of Dictionary objects

The Dictionary object contains the following information:

Name Type Description
id string Dictionary identifier
source string Three letters language code of the source language for the dictionary
target string Three letters language code of the target language for the dictionary

For more information about the API, access: Get all Dictionaries.

Translations

Perform a Text Translation

The translateText method from LanguageWeaverClient, performs a text translation using a required TranslateTextRequest object.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        TranslateTextRequest translateTextRequest = new TranslateTextRequest()
                .setSourceLanguageId("eng")
                .setTargetLanguageId("fra")
                .setModel("generic")
                // provide list of dictionaries
                .addDictionary("689f06cf-36ba-4903-a530-da1f7766f478")
                .addDictionary("3d297ee3-0878-4ef7-9ee7-ca14b48e6956")
                .addInput("The weather is wonderful today!")
                .setInputFormat(Format.PLAIN);
        final TranslateTextResult translateTextResult = lwClient.translateText(translateTextRequest);
        // handle result
    }

See the complete sample on GitHub.

The TranslateTextRequest object contains the following information:

Name Type Mandatory Default value Description
sourceLanguageId string yes Three letters language code of the source language or auto which signals that the source language should be auto detected
targetLanguageId string yes Three letters language code of the target language
model string no* See notes below A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)
inputFormat Format no PLAIN Format of input content. See Input Formats.
input string array yes Content to be translated. Input is added using the addInput method. This can be called multiple times in order to perform array translations.
dictionaries string array no empty A string array containing dictionary ids. Dictionaries are added using the addDictionary method. This can be called multiple times if multiple dictionaries need to be used in a translation.
linguisticOptions map of strings no Map of strings containing pairs of linguistic option name and value. Values are case sensitive. You can only use the linguistic options that are available for that specific language pair. You can see what linguistic options are available for a language pair using this method call: Linguistic Options
Note

In order to use Linguistic Options feature you must enable it in your account

Text Input formats

Name Description
HTML HTML
PLAIN Plain text (UTF8)
XLINE Plain text, one sentence per line
TMX Translation Memory eXchange
XLIFF XML Localization Interchange File Format
BCM Proprietary format
XML Extensible Markup Language
SDLXML Treats every closing XML tag in the input as the end of a segment. The XML format in contrast does not make this assumption.
Note

If Edge product is selected, when performing a translation using sourceLanguageId, targetLanguageId and model combination, the selected language pair will be the first matching the combination.

Note

sourceLanguageId, targetLanguageId, model - can be used in the following combinations:

  • sourceLanguageId=[languageName] and targetLanguageId=[languageName] and model=[identifier for the language pair] - when all three are used they uniquely identify a language pair e.g: Eng-Fra-generic
  • sourceLanguageId=auto, targetLanguageId=[languageName], model- will be ignored even if specified - A language pair that matches the detected source language and the specified target language will be automatically selected. The selected language pair will be the first one (in alphabetical order) available in your account that matches the selection. E.g. if the detected source language is eng and the target language is fra and your account has subscriptions to (EngFra-Generic, EngFra-Sports, EngFra-Sports123) the language pair selected will be EngFra-Generic.

The TranslateTextResult object contains the following information:

Name Type Description
translation string Translated content

For more information about the API, access: Text Translations.

Perform a File Translation

The translateFile method from LanguageWeaverClient, performs a file translation using a required TranslateFileRequest object.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        TranslateFileRequest translateFileRequest = new TranslateFileRequest()
                .setSourceLanguageId("eng")
                .setTargetLanguageId("fra")
                .setModel("generic")
                // provide list of dictionaries
                .addDictionary("689f06cf-36ba-4903-a530-da1f7766f478")
                .addDictionary("3d297ee3-0878-4ef7-9ee7-ca14b48e6956")
                .setInputFormat(Format.PLAIN)
                // provide full path to the source file
                .setInputFile(Paths.get("java", "src", "main", "resources", "input", "input1.txt").toFile().getAbsolutePath())
                .setOutputFile(Paths.get("java", "src", "main", "resources", "output").toFile().getAbsolutePath() + File.separator + "input1-translated.txt");
    
        final TranslationFileResult translateFile = lwClient.translateFile(translateFileRequest);
        // handle result if outputFile not specified
    }

See the complete sample on GitHub.

The TranslateFileRequest object contains the following information:

Name Type Mandatory Default value Description
sourceLanguageId string yes Three letters language code of the source language or auto which signals that the source language should be auto detected
targetLanguageId string yes Three letters language code of the target language
model string no* See notes below A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)
inputFormat Format no PLAIN Format of input content. See Input Formats.
inputFile string yes The path for the input file that needs to be translated
outputFile string no The path for the output file that will contain the translated content. If the outputFile is not provided, the translated content will be returned as part of the TranslationFileResult as an InputStream.
dictionaries string array no empty A string array containing dictionary ids. Dictionaries are added using the addDictionary method. This can be called multiple times if multiple dictionaries need to be used in a translation.
pdfConverter PdfConverter no empty* An enum representing one of the three supported options for the pdf converter: SMART_SELECTION, ABBYY and STANDARD. ABBYY is used with better results for scanned PDFs. With SMART_SELECTION Language Weaver will choose the best pdf converter option for given input, the choice will be made between ABBYY and STANDARD.
linguisticOptions map of strings no Map of strings containing pairs of linguistic option name and value. Values are case sensitive. You can only use the linguistic options that are available for that specific language pair. You can see what linguistic options are available for a language pair using this method call: Linguistic Options
Note

In order to use Linguistic Options feature you must enable it in your account

Note

If Edge product is selected, when performing a translation using sourceLanguageId, targetLanguageId and model combination, the selected language pair will be the first matching the combination.

Note

Pdf Converter default value:

  • Cloud will automatically use STANDARD
  • Edge (licensed with ABBYY) will automatically use ABBYY when the source file is a scanned PDF, or if the source language is right-to-left (RTL) script or one of the following: Chinese (Simplified and Traditional), Japanese, Korean, Vietnamese, Thai, Hindi or Burmese; Edge will use standard conversion for all other source languages when the source file is not a scanned PDF
Note

sourceLanguageId, targetLanguageId, model - can be used in the following combinations:

  • sourceLanguageId=[languageName] and targetLanguageId=[languageName] and model=[identifier for the language pair] - when all three are used they uniquely identify a language pair e.g: Eng-Fra-generic
  • sourceLanguageId=auto, targetLanguageId=[languageName], model- will be ignored even if specified - A language pair that matches the detected source language and the specified target language will be automatically selected. The selected language pair will be the first one (in alphabetical order) available in your account that matches the selection. E.g. if the detected source language is eng and the target language is fra and your account has subscriptions to (EngFra-Generic, EngFra-Sports, EngFra-Sports123) the language pair selected will be EngFra-Generic.
Note
  • For image input formats, output format is PLAIN text (.txt)
  • For EML and MSG input formats, output format is PLAIN text (.txt)
  • For PDF input format, output format is DOCX (.docx)
  • For all other input formats, output format is the same as the input format

The TranslationFileResult object contains the following information:

Name Type Description
fileContent InputStream InputStream representing the translated file content. This is populated when the translated content is not stored in an output file on the disk, based on the outputFile value.

For more information about the API, access: File Translations.

Perform a Batch File Translation

The translateBatchFile method from LanguageWeaverClient, performs a batch file translation using a required TranslateBatchFileRequest object.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        TranslateBatchFileRequest translateFileRequest = new TranslateBatchFileRequest()
                .setSourceLanguageId("eng")
                .setTargetLanguageId("fra")
                .setModel("generic")
                // provide list of dictionaries
                .addDictionary("689f06cf-36ba-4903-a530-da1f7766f478")
                .addDictionary("3d297ee3-0878-4ef7-9ee7-ca14b48e6956")
                // provide full path to the input and output folders
                .setInputBatchFolderPath(Paths.get("java", "src", "main", "resources", "input").toFile().getAbsolutePath())
                .setOutputBatchFolderPath(Paths.get("java", "src", "main", "resources", "output").toFile().getAbsolutePath());
    
        lwClient.translateBatchFile(translateFileRequest);
    }

See the complete sample on GitHub.

The TranslateBatchFileRequest object contains the following information:

Name Type Mandatory Default value Description
sourceLanguageId string yes Three letters language code of the source language or auto which signals that the source language should be auto detected
targetLanguageId string yes Three letters language code of the target language
model string no* See notes below A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)
inputBatchFolderPath string yes The path to the folder that contains the input files
outputBatchFolderPath string yes The path to the folder where the corresponding translated files will be added
dictionaries string array no empty A string array containing dictionary ids. Dictionaries are added using the addDictionary method. This can be called multiple times if multiple dictionaries need to be used in a translation.
pdfConverter PdfConverter no empty* An enum representing one of the three supported options for the pdf converter: SMART_SELECTION, ABBYY and STANDARD. ABBYY is used with better results for scanned PDFs. With SMART_SELECTION Language Weaver will choose the best pdf converter option for given input, the choice will be made between ABBYY and STANDARD.
linguisticOptions map of strings no Map of strings containing pairs of linguistic option name and value. Values are case sensitive. You can only use the linguistic options that are available for that specific language pair. You can see what linguistic options are available for a language pair using this method call: Linguistic Options
Note

In order to use Linguistic Options feature you must enable it in your account

Note

If Edge product is selected, when performing a translation using sourceLanguageId, targetLanguageId and model combination, the selected language pair will be the first matching the combination.

Note

Pdf Converter default value:

  • Cloud will automatically use STANDARD
  • Edge (licensed with ABBYY) will automatically use ABBYY when the source file is a scanned PDF, or if the source language is right-to-left (RTL) script or one of the following: Chinese (Simplified and Traditional), Japanese, Korean, Vietnamese, Thai, Hindi or Burmese; Edge will use standard conversion for all other source languages when the source file is not a scanned PDF
Note

sourceLanguageId, targetLanguageId, model - can be used in the following combinations:

  • sourceLanguageId=[languageName] and targetLanguageId=[languageName] and model=[identifier for the language pair] - when all three are used they uniquely identify a language pair e.g: Eng-Fra-generic
  • sourceLanguageId=auto, targetLanguageId=[languageName], model- will be ignored even if specified - A language pair that matches the detected source language and the specified target language will be automatically selected. The selected language pair will be the first one (in alphabetical order) available in your account that matches the selection. E.g. if the detected source language is eng and the target language is fra and your account has subscriptions to (EngFra-Generic, EngFra-Sports, EngFra-Sports123) the language pair selected will be EngFra-Generic.
Note
  • For image input formats, output format is PLAIN text (.txt)
  • For EML and MSG input formats, output format is PLAIN text (.txt)
  • For PDF input format, output format is DOCX (.docx)
  • For all other input formats, output format is the same as the input format

For more information about the API, access: File Translations.

Content Insights

Create Content Insights For Existing Translations

The getContentInsightsForTranslations method from LanguageWeaverClient performs content insights for a file that was already translated.

    try (LanguageWeaverClient lwClient = new SdkFactory().getLanguageWeaverClient(new ClientConfiguration())) {
        TranslateFileRequest translateFileRequest = new TranslateFileRequest()
            .setSourceLanguageId("eng")
            .setTargetLanguageId("fra")
            .setModel("generic")
            // provide list of dictionaries
            .addDictionary("689f06cf-36ba-4903-a530-da1f7766f478")
            .addDictionary("3d297ee3-0878-4ef7-9ee7-ca14b48e6956")
            .setInputFormat("plain")
            // provide full path to the source file
            .setInputFile(Paths.get("java", "src", "main", "resources", "input", "input1.txt").toFile().getAbsolutePath())
            .setOutputFile(Paths.get("java", "src", "main", "resources", "output").toFile().getAbsolutePath() + File.separator + "input1-translated.txt");

        ContentInsightsRequest contentInsightsRequest = new ContentInsightsRequest()
            .addTranslationId(lwClient.translateFile(translateFileRequest).getTranslationId());
        
        ContentInsightsResult contentInsightsResult = lwClient.getContentInsightsForTranslations(contentInsightsRequest);
    }

See the complete sample on GitHub.

The ContentInsightsRequest object contains the following information:

Name Type Description
translationIds string array A string array containing translation ids

The ContentInsightsResult object contains the following information:

Name Type Description
summarization Summarization Object containing the sentences from the input files that were selected as part of the summary

The Summarization object contains the following information:

Name Type Description
segments Segment array The array with the sentences from the input files that were selected as part of the summary

The Segment object contains the following information:

Name Type Description
text string A sentence from the input files that was selected to be part of the summary
score float A score between 0 and 1. The higher the score, the more representative the sentence is for the summary
Note

If Edge product is selected, you can perform content insights for only one file that was already translated. If you want to perform content insights for multiple files, please use CloudLanguageWeaverClient!

Feedback Management

Create Feedback

The createFeedback method from LanguageWeaverClient creates a translation feedback using a required CreateFeedbackRequest object.

    CreateFeedbackRequest createFeedbackRequest = new CreateFeedbackRequest()
        .setSourceLanguageId("eng")
        .setTargetLanguageId("fra")
        .setModel("generic")
        .setSourceText("sourceText")
        .setTargetText("targetText")
        .setSuggestedTranslation("suggestedTranslation");

     FeedbackResult feedback = lwClient.createFeedback(createFeedbackRequest);

See the complete feedback samples on GitHub .

The CreateFeedbackRequest object contains the following information:

Name Type Mandatory Default value Description
sourceLanguageId string yes Three letters language code of the source language
targetLanguageId string yes Three letters language code of the target language
model string yes A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)
sourceText string yes Text provided to be translated
targetText string yes Translation provided by machine translation
suggestedTranslation string yes Expected translation

The FeedbackResult object contains the following information:

Name Type Description
feedbackId string Feedback identifier
sourceLanguageId string Three letters language code of the source language
targetLanguageId string Three letters language code of the target language
model string A string representing a unique identifier for the language pair combination sourceLanguageId-targetLanguageId-model. (e.g. generic)
sourceText string Text provided to be translated
targetText string Translation provided by machine translation
suggestedTranslation string Expected translation
approvalState ApprovalStatus The approval status of the feedback (APPROVED, REJECTED, PENDING)
feedbackAuditData AuditData Object containing details about the lifecycle of the feedback
approvalAuditData AuditData Object containing details about the lifecycle of the feedback's approval

The AuditData object contains the following information:

Name Type Description
createdByUserEmail string The email of the user who created the feedback
creationDate string Creation date of the feedback
lastModifiedByUserEmail string The email of the user who last modified the feedback
lastModifyDate string The date when the feedback was last modified

For more information about the API, access: Feedback operations.

Update Feedback

The updateFeedback method from LanguageWeaverClient updates a translation feedback using a required UpdateFeedbackRequest object.

     UpdateFeedbackRequest updateFeedbackRequest = new UpdateFeedbackRequest()
        .setFeedbackId("feedbackId")
        .setSuggestedTranslation("new suggested translation");

     FeedbackResult feedback = lwClient.updateFeedback(updateFeedbackRequest);

You can also obtain UpdateFeedbackRequest from FeedbackResult using the toUpdateRequest method which will transfer the feedback's updatable information into a new update request.

    UpdateFeedbackRequest updateFeedbackRequest = feedback.toUpdateRequest();

See the complete feedback samples on GitHub .

The UpdateFeedbackRequest object contains the following information:

Name Type Mandatory Default value Description
feedbackId string yes The id of the feedback to be updated
suggestedTranslation string no Expected translation

The method returns a FeedbackResult object which is described here.

For more information about the API, access: Feedback operations.

Update Feedback Approval Status

The updateFeedbackApproval method from LanguageWeaverClient can be used to update the approval status of an existing translation feedback using a required UpdateFeedbackApprovalRequest object. The object can be constructed manually:

     UpdateFeedbackApprovalRequest updateApprovalRequest = new UpdateFeedbackApprovalRequest()
        .setFeedbackId("feedbackId")
        .setApprovalStatus(ApprovalStatus.APPROVED);

     FeedbackResult feedback = lwClient.updateFeedbackApproval(updateApprovalRequest);

You can also obtain UpdateFeedbackApprovalRequest from FeedbackResult using the toUpdateApprovalRequest(ApprovalStatus) method which will contain the feedback's id and the requested approval status.

    UpdateFeedbackApprovalRequest updateApprovalRequest = feedback.toUpdateApprovalRequest(ApprovalStatus.APPROVED);

See the complete feedback samples on GitHub .

The UpdateFeedbackApprovalRequest object contains the following information:

Name Type Mandatory Default value Description
feedbackId string yes The id of the feedback to be updated
approvalStatus ApprovalStatus yes The approval status of the feedback (APPROVED, REJECTED, PENDING)

The method returns a FeedbackResult object which is described here.

For more information about the API, access: Feedback operations.

Delete Feedback

The deleteFeedback method from LanguageWeaverClient can be used to delete an existing translation feedback using a required DeleteFeedbackRequest object.

    DeleteFeedbackRequest deleteFeedbackRequest = new DeleteFeedbackRequest()
        .setFeedbackId("feedbackId");

    lwClient.deleteFeedback(deleteFeedbackRequest);

You can also obtain DeleteFeedbackRequest from FeedbackResult using the toDeleteRequest method which will contain the feedback's id.

    DeleteFeedbackRequest deleteFeedbackRequest = feedback.toDeleteRequest();

See the complete feedback samples on GitHub .

The DeleteFeedbackRequest object contains the following information:

Name Type Mandatory Default value Description
feedbackId string yes The id of the feedback to be deleted

The method returns a FeedbackResult object which is described here.

For more information about the API, access: Feedback operations.

Get All Feedback

By using the getFeedback method from LanguageWeaverClient, the list of available feedback will be returned, corresponding to the given client identifier.
The feedback can be filtered by various criteria using an FilterFeedbackRequest.
This is a paginated request thus the pageNumber parameter is mandatory while the pageSize will default to 100 if not specified.

  FilterFeedbackRequest filterFeedbackRequest = new FilterFeedbackRequest()''
        .setApprovalStatus(ApprovalStatus.APPROVED)
        .setUser("userId")
        .setStartDate("10/10/2021")
        .setEndDate("10/10/2022");

  FeedbackListResult feedbackList = lwClient.getFeedback(filterFeedbackRequest, 1, 50);

See the complete feedback samples on GitHub .

The getFeedback method has the following parameters:

Name Type Mandatory Default Description
pageNumber integer yes Number specifying the requested page number
pageSize integer no 100 Number specifying the requested page size
filterRequest FilterFeedbackRequest no Object specifying the criteria by which the returned feedback to be filtered

The FilterFeedbackRequest object contains the following information:

Name Type Mandatory Default Description
startDate string yes A string representing the start date for the filtered feedback in the format dd/mm/yyyy
endDate string yes A string representing the end date for the filtered feedback in the format dd/mm/yyyy
user string no The id of the user who created the feedback (Cloud) or the username of the user who created the feedback (Edge)
approvalStatus ApprovalStatus no The approval status of the feedback (APPROVED, REJECTED, PENDING)

The FeedbackListResult object contains the following information:

Name Type Description
feedbackList array Array of FeedbackResult objects
pageNumber integer Number specifying the requested page number
pageSize integer Number specifying the requested page size
totalCount long Total number of filtered feedbacks for the given account

For more information about the API, access: Feedback operations.