Translations

List translations

Example Request:

curl "https://controller-host:8001/api/v2/translations?startTimeQueued=2019-01-01+11%3A26%3A45.158516672Z" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translations": [
        {
            "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
            "profile": {
                "username": "jsmith@example.com",
                "title": "example translation",
                "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                "encoding": "utf-8",
                "inputFormat": "text/html",
                "pdfConverter": "",
                "pdfPageCount": 0,
                "imageConverter": "",
                "dictionaryIds": [
                    "dict1_c95c72dd2f138da2a46c872a40616eb1",
                    "dict2_397e8373985929881616bcaa4805844a"
                ],
                "outputFormat": "",
                "highlightDictionary": true,
                "highlightBrand": true,
                "highlightFeedback": true,
                "unknownMode": "hide",
                "highlightUnknown": false,
                "markSegments": true,
                "sourceRequested": false,
                "generateMetadata": false,
                "translationMethod": "MTE",
                "labels": [
                    {
                        "id": 4,
                        "name": "Legal"
                    },
                    {
                        "id": 28,
                        "name": "Medical"
                    }
                ],
                "includeTextContent": false
            },
            "result": {
                "completedSegments": 64,
                "inputSize": 3613,
                "sourceCharacterCount": 3498,
                "sourceWordCount": 689,
                "targetCharacterCount": 3840,
                "targetWordCount": 766,
                "totalSegments": 64,
                "outputSize": 4006,
                "progress": 100,
                "wordsPerMinute": 52065,
                "qualityEstimation": {
                    "good": 73.333336,
                    "adequate": 10.123456,
                    "poor": 16.543211
                }
            },
            "timestamps": {
                "queued": "2018-06-21 19:03:31.799810031Z",
                "started": "2018-06-21 19:03:32.113048776Z",
                "done": "2018-06-21 19:03:34.872942468Z"
            },
            "errorMessage": "",
            "state": "done",
            "substate": "succeeded"
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of translations. If the caller is an admin user, translations for all users are returned, unless the username field is provided to return only that specific user's translations. If the caller is a non-admin user, only the caller's translations are returned.

HTTP Request

GET /api/v2/translations

Request Parameters

Name Type Description Default Value
username (optional) string Show only translations created by this user. This field is ignored for non-admin users.
statuses (optional) string Show only translations with the given comma-separated states. (see table of possible states)
labels (optional) string Show only translations with the given comma-separated labels.
startTimeQueued (optional) string Show only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
endTimeQueued (optional) string Show only translations that were queued on or before the given timestamp. (see timestamps for formatting)
translationMethod (optional) string Show only translations with the given translationMethod. (see list of supported translation methods)
title (optional) string Show only translations with the given title as a substring.
sourceLanguageId (optional) string Show only translations with the given sourceLanguageId (3-letter code).
targetLanguageId (optional) string Show only translations with the given targetLanguageId (3-letter code).
languagePairId (optional) string Show only translations with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId.
page (optional) int Page number to return 1
perPage (optional) int Number of translations to return per page 25

Returns

Returns a list of translations as a TranslationList object with the following attributes:

Name Type Description
translations array of objects List of translations as an array of Translation objects
page int Page number returned
perPage int Number of translations returned per page
totalPages int Total number of pages available
totalItems int Total number of translations

Create a translation (asynchronously)

Example Request:

curl "https://controller-host:8001/api/v2/translations" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d highlightBrand="true" \
	-d highlightDictionary="true" \
	-d highlightFeedback="true" \
	-d labels="Health" \
	-d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
	--data-urlencode dictionaryIds="dict1,dict2" \
	--data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
	--data-urlencode linguisticOptions="Formality:Formal" \
	--data-urlencode outputFormat="application/x-xliff" \
	--data-urlencode title="example translation"

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"
}

Create an asynchronous translation job and receive back its identifier. This identifier can then be used to monitor the job's status and retrieve the translation results after successful completion.

HTTP Request

POST /api/v2/translations

Request Parameters

Name Type Description Default Value
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded content to translate
inputFormat (optional) string Format of input document (see table of possible input formats)
pdfConverter (optional) string Converter to use for PDF conversions. Choices: Standard to use standard conversion and Abbyy to use ABBYY FineReader for enhanced conversion. If empty, 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.
imageConverter (optional) string Converter to use for image to text conversions. Choices: Standard to use standard conversion and Abbyy to use ABBYY FineReader when licensed. Standard
outputFormat (optional) string Format of output document (see table of possible output formats)
title (optional) string Title of translation job
encoding (optional) string Encoding of input content (see list of supported character encodings) utf-8
dictionaryIds (optional) string User dictionaries to be used for translation -- comma-separated identifiers, in decreasing order of precedence
highlightDictionary (optional) boolean Whether to highlight dictionary translations in the output. This only applies if dictionaryIds is set to at least one dictionary, and both inputFormat and outputFormat are text/html. false
highlightBrand (optional) boolean Whether to highlight brand translations in the output. This only applies to non-search pattern brand matches, and both inputFormat and outputFormat are text/html. false
highlightFeedback (optional) boolean Whether to highlight feedback translations in the output. This only applies to feedback matches, and both inputFormat and outputFormat are text/html. false
unknownMode (optional) string How to display unknown words. Choices: hide to omit unknown words from the output, original to include original unknown words as is, transliteration to transliterate unknown words, or transliterationAndOriginal to show both the transliteration and the original (in parentheses). transliteration and transliterationAndOriginal display transliterations if the source language supports transliteration, otherwise the original unknown words are displayed. transliteration
highlightUnknown (optional) boolean Whether to highlight unknown words or their transliterations. This only applies if both inputFormat and outputFormat are text/html. false
markSegments (optional) boolean Whether to mark source and target segments in the output. This only applies if inputFormat and outputFormat are text/html. false
generateMetadata (optional) boolean Generate metadata in addition to the translation (requires more computation) false
labels (optional) string Labels for translation to be associated with -- comma-separated identifiers
includeTextContent (optional) boolean Generate a separate translation output in text/plain format. This only applies if outputFormat is not already text/plain false
linguisticOptions (optional) array of key:value strings Linguistic options to use for translation; (see list language-pairs) to display available linguistic options.

Returns

Returns an asynchronous translation job as an AsyncTranslation object with the following attributes:

Name Type Description
translationId string Identifier of newly-created translation job

Input Formats

XML Formats

MIME Type File Extensions Description
text/html .htm, .html, .xhtml HTML
text/xml .xml XML
text/x-sdl-strict-xml .sdlxml XML with strict segmentation after each XML tag
text/x-tmx .tmx Translation Memory eXchange (TMX)
application/x-xliff .xliff XML Localization Interchange File Format v1.x (XLIFF)
application/xliff .xliff XML Localization Interchange File Format v2.x (XLIFF)
text/sgml .sgml, .sgm SGML

Text Formats

MIME Type File Extensions Description
text/plain .txt Plain text
text/x-line .xline Plain text, one sentence per line

Image Formats

MIME Type File Extensions Description
image/gif .gif Graphics Interchange Format (GIF)
image/jpeg .jpg, .jpeg JPEG
image/png .png Portable Network Graphics (PNG)
image/tiff .tiff, .tif Tagged Image File Format (TIFF)

Email Formats

MIME Type File Extensions Description
application/vnd.ms-outlook .msg Microsoft Outlook Email Message
message/rfc822 .eml Message (RFC 822)

Rich Formats

MIME Type File Extensions Description
application/pdf .pdf Adobe Acrobat (PDF)
application/rtf .rtf Rich Text Format (RTF)
application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx, .dotx, .docm, .dotm Microsoft Word (Office Open XML)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx, .xltx, .xlsm, .xltm, .xlam Microsoft Excel (Office Open XML)
application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx, .potx, .ppsx, .ppam, .pptm, .potm, .ppsm Microsoft PowerPoint (Office Open XML)
application/msword .doc, .dot Microsoft Word (97-2003)
application/vnd.ms-excel .xls, .xlt, .xla, .xlsb Microsoft Excel (97-2003)
application/vnd.ms-powerpoint .ppt, .pot, .pps, .ppa Microsoft PowerPoint (97-2003)
application/vnd.oasis.opendocument.text .odt OpenDocument Text
application/vnd.oasis.opendocument.spreadsheet .ods OpenDocument Spreadsheet
application/vnd.oasis.opendocument.presentation .odp OpenDocument Presentation
application/x-wps-writer .wps WPS Writer
application/x-wps-spreadsheet .et WPS Spreadsheet
application/x-wps-presentation .dps WPS Presentation
application/x-mimearchive .mhtml, .mht MHTML

Output Formats

MIME Type Description
default or empty Default output:
  • For image, audio and email input formats, output text/plain
  • For application/pdf input, output text/plain if it is an image-only PDF, otherwise output application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • For all other input formats, output the same as the input format
text/plain Plain text
application/x-xliff XML Localization Interchange File Format (v1.2)
application/xliff XML Localization Interchange File Format (v2.1)
text/x-tmx Translation Memory eXchange

Translation Methods

Method Description
MTE Edge (default)
GroupShare GroupShare

Timestamps

Unless otherwise stated, timestamps adhere to yyyy-MM-dd HH:mm:ss.SSS (example: 2006-01-02 15:04:05.999999999Z).

Create a quick translation (synchronously)

Example Request:

curl "https://controller-host:8001/api/v2/translations/quick" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d highlightBrand="true" \
	-d highlightDictionary="true" \
	-d highlightFeedback="true" \
	-d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
	--data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
	--data-urlencode linguisticOptions="Formality:Formal"

Example Response:

{
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "translation": "Qydlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkJ2VudHLDqWUuCg=="
}

Create a synchronous translation and receive back the translation in the same call. This method is recommended for small, plain text inputs under 1KB in size, although no constraint is enforced. Only the translation and not a job identifier is returned, so the job cannot be tracked or managed in any way.

HTTP Request

POST /api/v2/translations/quick

Request Parameters

Name Type Description Default Value
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded content to translate
inputFormat (optional) string Format of input document (see table of possible input formats)
title (optional) string Title of translation job
encoding (optional) string Encoding of input content (see list of supported character encodings) utf-8
dictionaryIds (optional) string User dictionaries to be used for translation -- comma-separated identifiers, in decreasing order of precedence
highlightDictionary (optional) boolean Whether to highlight dictionary translations in the output. This only applies if dictionaryIds is set to at least one dictionary, and both inputFormat and outputFormat are text/html. false
highlightBrand (optional) boolean Whether to highlight brand translations in the output. This only applies to non-search pattern brand matches, and both inputFormat and outputFormat are text/html. false
highlightFeedback (optional) boolean Whether to highlight feedback translations in the output. This only applies to feedback matches, and both inputFormat and outputFormat are text/html. false
unknownMode (optional) string How to display unknown words. Choices: hide to omit unknown words from the output, original to include original unknown words as is, transliteration to transliterate unknown words, or transliterationAndOriginal to show both the transliteration and the original (in parentheses). transliteration and transliterationAndOriginal display transliterations if the source language supports transliteration, otherwise the original unknown words are displayed. transliteration
highlightUnknown (optional) boolean Whether to highlight unknown words or their transliterations. This only applies if both inputFormat and outputFormat are text/html. false
markSegments (optional) boolean Whether to mark source and target segments in the output. This only applies if inputFormat and outputFormat are text/html. false
generateMetadata (optional) boolean Generate metadata in addition to the translation (requires more computation) false
linguisticOptions (optional) array of key:value strings Linguistic options to use for translation; (see list language-pairs) to display available linguistic options.

Returns

Returns a synchronous translation as a SyncTranslation object with the following attributes:

Name Type Description
languagePairId string Identifier of language pair used for translation
translation string Base64-encoded output translation
detectedSourceLanguageId string Automatically-detected source language identifier of the input

Retrieve a translation's status

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeTextContent": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "2018-06-21 19:03:32.113048776Z",
        "done": "2018-06-21 19:03:34.872942468Z"
    },
    "errorMessage": "",
    "state": "done",
    "substate": "succeeded"
}

Return information about and status of an asynchronous translation job.

HTTP Request

GET /api/v2/translations/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the specified translation as a Translation object with the following attributes:

Name Type Description
translationId string Identifier of translation job
profile object Description of translation job in the queue (expanded below)
→ username string Username of user who created translation job
→ title string Title of translation job
→ url string URL of webpage to be translated [not used]
→ languagePairId string Identifier of language pair or language pair chain
→ encoding string Source document encoding
→ inputFormat string Format of input document (see table of possible input formats)
→ dictionaryIds array of strings Dictionaries used for translation
→ outputFormat string Format of output document (see table of possible output formats)
→ highlightDictionary string Whether to highlight dictionary translations in the output
→ highlightBrand string Whether to highlight brand translations in the output
→ highlightFeedback string Whether to highlight feedback translations in the output
→ unknownMode string How to display unknown words
→ highlightUnknown string Whether to highlight unknown words or their transliterations
→ markSegments string Whether to mark source and target segments in the output.
→ generateMetadata boolean Whether metadata of output will be produced and included in response
→ translationMethod string Method used to translate the job
→ labels array of labels Labels associated with this translation
result object Description of translation job in the queue (expanded below)
→ completedSegments int Number of segments that have successfully been translated
→ detectedSourceLanguageId string Automatically-detected source language identifier of the input
→ detectedEncoding string Automatically-detected script encoding identifier of the input
→ inputSize int Size of the input document in bytes
→ sourceCharacterCount int Number of input characters in the document translated so far
→ sourceWordCount int Number of input words in the document translated so far
→ targetCharacterCount int Number of output characters in the document translated so far
→ targetWordCount int Number of output words in the document translated so far
→ totalSegments int Total number of segments in the input
→ outputSize int Size of the output document in bytes
→ progress int Translation progress (percent completion)
→ wordsPerMinute int Translation rate (words per minute)
timestamps object Timestamps of checkpoints in translation job progress (expanded below) in UTC
→ queued string When the translation job was created before being submitted to a job engine (when state became preparing)
→ started string When the translation job was submitted to a job engine (when state became inProgress)
→ done string When the translation job result was returned from a job engine (when state became done)
errorMessage string Error message if state is done and substate is failed
state string Translation job state (see table below)
substate string Translation job substate (see table below)

Translation Job States and Their Substates

The status of a job is represented by a state and a substate. There are three possible states, and each state has a number of possible substates. The state provides a high-level indication of whether a job has started, is in progress, or has ended, while the substate provides more detailed information about the state.

State Substate Description
preparing job is being prepared for translation
  created job has been created
  transcribing job involves audio input and it is being transcribed
  scheduled job has been scheduled for dispatch
  dispatching job is being dispatched to a job engine
inProgress job is being processed
  initializing job engine is getting ready to process job
  preprocessing job is being preprocessed
  translating job is being translated
  postprocessing job is being postprocessed
  converting job is being converted for the interactive translation editor
done job has finished
  canceled job has been canceled by user
  failed job has failed
  succeeded job has completed successfully

Download a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/download" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

Qydlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkJ2VudHLDqWUuCg==

Return the translated output of an asynchronous translation job. The job must have been successfully completed first.

HTTP Request

GET /api/v2/translations/{translationId}/download

Path Parameters

Name Type Description
translationId string Identifier of translation job

Request Parameters

Name Type Description Default Value
format (optional) string The file format of the translation job to download. Choices: default to download the original output format of the translation job result, text/plain to download the plain text format of the translation job result. The text/plain option is only available if the translation job was performed with includeTextContent set to true default

Returns

Returns the output of a translation in base64 encoding.

Download translation(s) in a zip file

Example Request:

curl "https://controller-host:8001/api/v2/translations/download-archive?startTimeQueued=2019-01-01+11%3A26%3A45.158516672Z&translationIds=bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd%2C6f0985dd-e6b0-490a-8cec-27a45bc922c0" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

application/zip

Return the translated output(s) of completed asynchronous translation job(s) in a zip file.

HTTP Request

GET /api/v2/translations/download-archive

Request Parameters

Name Type Description Default Value
translationIds (optional) string Comma separated identifier of translation job(s)
  • Total output size of translations limited to 1GB
username (optional) string Download only translations created by this user. This field is ignored for non-admin users.
statuses (optional) string Download only translations with the given comma-separated states. (see table of possible states)
labels (optional) string Download only translations with the given comma-separated labels.
startTimeQueued (optional) string Download only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
endTimeQueued (optional) string Download only translations that were queued on or before the given timestamp. (see timestamps for formatting)
translationMethod (optional) string Download only translations with the given translationMethod. (see list of supported translation methods)
title (optional) string Download only translations with the given title as a substring.
sourceLanguageId (optional) string Download only translations with the given sourceLanguageId (3-letter code).
targetLanguageId (optional) string Download only translations with the given targetLanguageId (3-letter code).
languagePairId (optional) string Download only translations with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId.

Returns

Returns the output(s) of translation(s) in a zip file.

Retrieve metadata of a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/metadata" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

ew0KICAgICJhcHBJZCI6ICI4LjAuMCIsDQogICAgImpvYklkIjogNSwNCiAgICAic291cmNlTGFuZ3VhZ2VJZCI6ICJlbmciLA0KICAgICJ0YXJnZXRMYW5ndWFnZUlkIjogImZyYSIsDQogICAgImxhbmd1YWdlUGFpcklkIjogIkVuZ0ZyYV9HZW5lcmljX1NSVl9QQl84XzBfeF8wIiwNCiAgICAic2VnbWVudCI6IHsNCiAgICAgICAgImlkIjogMCwNCiAgICAgICAgInNvdXJjZVRva2VucyI6ICJUaGlzIGlzIGEgc2FtcGxlIGlucHV0IHRleHQgX19MV19BVF9fLiIsDQogICAgICAgICJzb3VyY2VUb2tlbnNMb3dlcmNhc2UiOiAidGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0IF9fTFdfQVRfXy4iLA0KICAgICAgICAidGFyZ2V0VG9rZW5zIjogIkMgX19MV19BVF9fJ19fTFdfQVRfXyBlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkIF9fTFdfQVRfXydfX0xXX0FUX18gZW50csOpZSBfX0xXX0FUX18uIiwNCiAgICAgICAgInRhcmdldFRva2Vuc0xvd2VyY2FzZSI6ICJjIF9fTFdfQVRfXydfX0xXX0FUX18gZXN0IHVuIGV4ZW1wbGUgZGUgdGV4dGUgZCBfX0xXX0FUX18nX19MV19BVF9fIGVudHLDqWUgX19MV19BVF9fLiINCiAgICB9DQp9DQo=

Return the metadata of an asynchronous translation job. The translation must have been successfully completed first.

HTTP Request

GET /api/v2/translations/{translationId}/metadata

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the metadata of a translation in JSON format in base64 encoding.

Retrieve content insights of a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/content-insights" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "title": "example translation",
    "summary": [
        {
            "segment": "This is an example of a summarized segment",
            "score": 0.7950247
        },
        {
            "segment": "Here is another summarized segment.",
            "score": 0.89506936
        },
        {
            "segment": "This is the last summarized segment in the group.",
            "score": 0.8836193
        }
    ]
}

Return the content insights of an asynchronous translation job. The translation must have been successfully completed first.

HTTP Request

GET /api/v2/translations/{translationId}/content-insights

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the content insights of a translation in JSON format in base64 encoding.

Name Type Description
title string Title of the translation document
summary array of objects Summarized segments of the document
→ segment string Segment of the summarization entry
→ score float Score rating the importance of the segment in the summary. 0 is minimum, 1 is maximum.

Create a translation via GroupShare

Example Request:

curl "https://controller-host:8001/api/v2/translations/group-share" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
	--data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
	--data-urlencode title="example translation"

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"
}

Submit input to GroupShare for translation and editing. Output format is the same as input format.

HTTP Request

POST /api/v2/translations/group-share

Request Parameters

Name Type Description Default Value
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded utf-8 content to translate
inputFormat (optional) string Format of input document (see table of possible input formats)
title (optional) string Title of translation job

Returns

Returns an asynchronous translation job as an AsyncTranslation object with the following attributes:

Name Type Description
translationId string Identifier of newly-created translation job

Retrieve the URL to edit a GroupShare translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/group-share/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "User",
    "link": "http://groupShareHost:80/#editor/project/075dd207-38d2-4262-a23e-babc751b4751/languageFile/62f74351-217c-42d2-8e22-0f0949d8dfd0",
    "token": "AAIAAFeH8_HfLlPA9Fbp692hLm__XmVhW2V04k294kfxD7LM7ZXSFfw1KpUFcQVw-sH1_iScOCTHfn1XSownycm9q6cXL39pqoSlEvhlTkC2VZNAM9Em6EPK92aanhLkQeP_bKjP-dLPzRejBrKNH0hcwKGs25ue4K2NvkT6Nz5D8PAAzA-qH8zObV20uqjdzAMZRS7ZrhjL79cYGNPXenzI4HG3EhMKz7hbJ1G9qP1KGZEdLUiFHo4sC6Zby_A6HR3a3cXSaIjZ_MrTKWmTWgbC13aq3iJmRU_Z5Z420sbN4rN5l9JsPedRhTYEfwDEtWvZO37tUmbZm-oa03J4c32WsZUippAxxctkQpsWtCuliw5i8wnWE_X7VTudD6JAAK8paWUM6EkjwDIJ6FiZELmWxqpGCX4NWu4ifQcWr6PgU9GC9TMf84CPT-1kNQbR-bhxYD7ggTcQVQSZ39w8QsBX8GN4Vl47r4vCasvx3r_zR6FOghIb96OKR2Ij3SbwLgorgZyTTjTlSHe0t1qFdtcsPj_EQ0WwdIyavCc0CtHY57o4ROuiNDqs1qDaYhRerwmowdVl6jwlpAFWkgnTVaTjZsKNoc-4Wk7T1RJfrMTN3NmF_nsIA7-A3UeOblm0oqJkHFEePj8psAtvpIBoCYRmduNcFreyUwskV5l6LKkc-4_gpAIAAAACAAAHeLpwx0HaoXposaNsJFzYFu5d4kBn8aL8IgKgZ_DDF1dCyfK2NLFIraDU2vUPUAwQbbtMIXiSSoTHAJBpX7_KQvtDmy_mgDAkC8vNdXZHXLJHllAgU7T6bfRToSzeZr0sozmxjddpGNtZgVnwD91rRaXW2Q12arI-KsGWG_nBfZA149jFIrNszoCscVwkZ5tS0IpsyduIsUks_60VVcuTjWbcqW0OCt99SG8fUtQsGNx8H0SAg84EKuVdDvDeCw-3u-qXJApE62s8FSqgHJkWL4g06_"
}

Return the URL to edit a GroupShare translation.

HTTP Request

GET /api/v2/translations/group-share/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns information to edit a a GroupShare translation as a GroupShareEditorDetails object with the following attributes:

Name Type Description
username string GroupShare's username as set in Edge
link string Link to GroupShare's editor
token string GroupShare's token

Cancel a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/cancel" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeTextContent": false
    },
    "result": {
        "completedSegments": 0,
        "inputSize": 0,
        "sourceCharacterCount": 0,
        "sourceWordCount": 0,
        "targetCharacterCount": 0,
        "targetWordCount": 0,
        "totalSegments": 0,
        "outputSize": 0,
        "progress": 0,
        "wordsPerMinute": 0,
        "qualityEstimation": {}
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "",
        "done": ""
    },
    "errorMessage": "",
    "state": "done",
    "substate": "canceled"
}

Cancel an asynchronous translation job. The canceled job remains in the queue.

HTTP Request

PUT /api/v2/translations/{translationId}/cancel

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the canceled translation as a Translation object.

Update a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d labels="Medical" \
	-d labels="Legal"

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeTextContent": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "2018-06-21 19:03:32.113048776Z",
        "done": "2018-06-21 19:03:34.872942468Z"
    },
    "errorMessage": "",
    "state": "done",
    "substate": "succeeded"
}

Update an asynchronous translation job's details

HTTP Request

PUT /api/v2/translations/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Request Parameters

Name Type Description Default Value
labels (optional) array of string Labels to update the translation job with

Returns

Returns the updated translation as a Translation object.

Delete a translation

Example Request:

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeTextContent": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "2018-06-21 19:03:32.113048776Z",
        "done": "2018-06-21 19:03:34.872942468Z"
    },
    "errorMessage": "",
    "state": "done",
    "substate": "succeeded"
}

Remove a translation job from the translation queue and history.

HTTP Request

DELETE /api/v2/translations/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the deleted translation as a Translation object.

Delete translations

Example Request:

curl "https://controller-host:8001/api/v2/translations/batch-delete" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	--data-urlencode startTimeQueued="2019-01-01 11:26:45.158516672Z" \
	--data-urlencode translationIds="bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd,6f0985dd-e6b0-490a-8cec-27a45bc922c0"

Example Response:

1

Remove translation jobs from the translation queue and history.

HTTP Request

DELETE /api/v2/translations/batch-delete

Request Parameters

Name Type Description Default Value
translationIds (optional) string Comma separated identifier of translation job(s)
username (optional) string Delete only translations created by this user. This field is ignored for non-admin users.
statuses (optional) string Delete only translations with the given comma-separated states. (see table of possible states)
labels (optional) string Delete only translations with the given comma-separated labels.
startTimeQueued (optional) string Delete only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
endTimeQueued (optional) string Delete only translations that were queued on or before the given timestamp. (see timestamps for formatting)
translationMethod (optional) string Delete only translations with the given translationMethod. (see list of supported translation methods)
title (optional) string Delete only translations with the given title as a substring.
sourceLanguageId (optional) string Delete only translations with the given sourceLanguageId (3-letter code).
targetLanguageId (optional) string Delete only translations with the given targetLanguageId (3-letter code).
languagePairId (optional) string Delete only translations with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId.

Returns

Returns the number of deleted translations.