API Route: Translate
Formatting requests
- You can use cURL, Postman, and python or javascript libraries, or any other procedure supported by REST APIs.
- The payload format is JSON.
- You must authenticate every request with a
x-api-keyheader.
Endpoints in this page
Translate
Translates a piece of content to the specified target language.
| POST https://agw.golinguist.com/linguistnow/resources/v1/translate | |||
| Request Parameters | |||
| Key | Type | Required | Description |
| rnResponseProjectId | integer | no | This is an ID number retrieved from a prior translation request. This is used to group translations together (for example, all the translations for a single ticket or chat session) and decreases the length of time to complete the translation. |
| sourceContent | string | yes | Content to translate |
| sourceLocale | string | yes | Language that you translate from |
| targetLocale | string | yes | Language that you translate to |
| contentTypeName | string | yes | Type of content being translated Valid value: "api" |
| translationType | string | yes | Type of translation vendor to use Valid values: "machine" |
| textType | string | yes | Type of content that is being translated Valid values: "html", "text" |
| evaluateQuality | boolean | no | Requests a Translation Quality Estimate (TQE) (see below) Valid values: "true", "false" |
| originalTranslationId | integer | no | Use this parameter to request a retranslation, using the TranslationId number provided in the response of the original translation.See Using the Original Translation ID parameter below. |
| optimization | boolean | no | Run the content through a simplification process before translation to improve the consistency and quality of the translation Valid values: "true", "false" See Using the Optimization parameter below. |
| incidentId | string | no | Store a single, CRM-specific, unique identifier for the Incident/Case/Ticket. This allows users to group related translations to an identified session. |
| consumerSourceId | string | no | This is an automatically generated ID number. |
| Request Example (JSON) | |||
{ "rnResponseProjectId": null, "sourceContent": "Hello. How may I help you?", "sourceLocale": "en", "targetLocale": "fr", "contentTypeName": "api", "translationType": "machine", "textType": "html", "evaluateQuality": "true" } | |||
| Response Parameters | |||
| belowQualityTarget | string | The TQE result for the translation Valid values: "true", "false" See Using the Translation Quality Estimate parameter below. |
|
| rnResponseProjectId | integer | The ID number for the project (See request parameters) |
|
| statusMessage | string | Status message returned from the Translation vendor. (For example, "Machine translation complete") | |
| translatedText | string | The translated content | |
| translationdId | integer | The ID of the translation | |
| wordCount | integer | The number of words that were translated | |
| Responses | |||
| Code 200 (Operation Successful) | |||
HTTP/1.1 200 OK { "belowQualityTarget": true, "rnResponseProjectId": "123456", "statusMessage": "Machine translation complete", "translatedText": "Bonjour. Comment puis-je vous aider ?", "translationId": 4994, "wordCount": 6 } | |||
| Possible Error Codes | |||
| 400 | Bad Request | ||
| 500 | Internal Server error | ||
| 528 | Unsupported Locale | ||
| 537 | Unexpected Error | ||
Using Optional Parameters
Using the Project ID parameter (rnResponseProjectId)
The Project ID parameter is a great tool to use when you want to associate several translations with each other. A typical scenario would be when you want to count all the translations that occurred for a given chat session or a given ticket. It is not necessary to specify a Project ID for the first translation in a chat session or ticket, but you can reuse the ID generated for this first translation for all subsequent translations that belong with this chat session or ticket.
The other main benefit is performance. Because all translations must carry a rnResponseProjectId, every time you do not specify an ID, some latency occurs as the system generate a new record that houses the rnResponseProjectId. Therefore, specifying an ID means faster processing times.
Using the Translation Quality Estimate parameter (evaluateQuality)
The Translation Quality Estimate (TQE) result is an automated quality assessment given to translation against a predefined quality threshold. To see an example of the feedback that TQE provides agents in Salesforce, see Using the Translation Quality Estimate (TQE). If a translation returns a "belowQualityTarget": true result, you can request a new translation using the originalTranslationId parameter (See next section).
Note that assessing a translation quality estimate may add a small amount of latency to the translation response time. Because of this, this feature is opt-in. Consult with your Customer Success Manager to see if your use case could benefit from TQE.
Using the Original Translation ID parameter ( originalTranslationId) to request a retranslation
If you are not satisfied with a translation (for example, if the TQE result is below target), you can request a new translation. Check the original translation response and copy the translationId number. Then, recreate your request and add the parameter originalTranslationId, with the number that you copied.
For example, in the response above, the translationId is 4994. This means your retranslation request should look like this: { "rnResponseProjectId": 123456, "sourceContent": "Hello. How may I help you?", "sourceLocale": "en", "targetLocale": "fr", "contentTypeName": "api", "translationType": "machine", "textType": "html", "evaluateQuality": "true" "originalTranslationId": 4994, }
Using the optimization parameter (optimization)
Optimization of the source content can be useful when you want to ensure the consistency and quality of translations, for example when you have a large pool of agents who may use different styles to address users. Automated optimization can help you use consistent language while saving on training costs.
For the sake of demonstration, suppose that the sourceContent is a flourished "Hello good sir, how may I help you on this glorious day?". This is a style that might not get the best results with machine translation.
Using the optimization: true parameter:
The source is processed before translation so that the text that is actually translated is much more straightforward (lines 2 to 4) and returns an equally straightforward translation (line 9):