Back to top image

Bring Your Own MT or LLM Service

 

If you’d like to integrate your own MT or AI translation service with Smartling, you can do so by setting up an MT Profile using the Common REST API provider. This guide walks you through the configuration process. The Common REST API provider allows you to connect a custom translation API to the Smartling platform.

This setup is for custom built in-house MT or AI services. If you want to use a particular commercial MT or LLM provider such as Amazon, DeepL, Google, GPT OpenAI, etc. please refer to the full list of supported providers and create an MT profile by following these instructions. 

Interested in integrating your own MT or AI translation service? Contact your Customer Success Manager to enable this feature in your account. 

Prerequisites 

Please note that it is essential to adhere to the API specifications outlined in this article. This includes accommodating all required fields and maintaining the specified formatting. Customizations, such as adding additional fields or altering the format, are not supported. We kindly ask that you review the entirety of this article before proceeding to ensure your system is appropriately adapted.

In addition, make sure you're familiar with JSONPath. JSONPath is a query language for JSON. You will use it to configure the expected response format, which defines how the translation data should be structured. You will also need a key/token for your MT or AI provider. 

The Common REST API Provider supports only token or key-based authentication. Other methods such as OAuth or basic auth, are not supported.

How to configure an MT Profile with a common REST provider 

Follow the steps below to integrate with your own MT or AI translation service in Smartling. 

Step 1: Add provider credentials in Smartling

  1. From the Account Settings > Machine Translation Settings, access the Provider Credentials tab. 
  2. Click Add Provider Credential.
    provider-credentials.png
    This opens a modal where you can save your provider key/token. Please enter the following information:
    • MT or LLM Provider (required):
      From the dropdown menu, select Common REST API Provider. 
    • Credential Name (required):
      Enter a name for your provider credential to help identify it. Ideally, this nickname should reflect which team owns the credential, which provider is used, and any other valuable information to help you identify this provider key.
      For example: AI provider Marketing Key
    • Credential Description (optional) 
    • Access token / key (required):
      Your access token or key provided by your MT or AI translation provider. 
    • Test Credential:
      Once you have provided all required information, please click "Test Credential" to check if the provider credential is fully functional. 
      • A success message will be displayed if the credential is working correctly. You can now proceed to associate this credential with an MT Profile. 
      • In case of any issues, an error message will be displayed. Please check if a valid provider credential was obtained, and if the API key and other details were entered correctly. 
  3. Click Save to create the credential. 

Step 2: Configure the MT Profile 

Once the provider credential has been saved and tested successfully, it can now be used to create an MT Profile. 

  1. From Account Settings > Machine Translation Settings, navigate to the Profiles tab.
  2. Click Create MT Profile. 
    create-MT-profile.png
  3. Enter the following information:
    • MT or LLM Provider (required): From the dropdown menu, select Common REST API Provider. 
    • MT Profile Name: Choose a name to identify the profile. We recommend including the provider name and any other relevant identifiers. 
      For example: AI Formal Profile 
    • Provider Credentials (required): From the dropdown menu, select the credential you created in the previous step. 
    • Service connection URL (required): Enter the base URL of your translation API. You can include the following placeholders. 
      • {apiKey}
      • {sourceLocale}
      • {targetLocale}
    • Request headers: If your API requires headers, you can include them here using the following placeholders.
      • {apiKey}
      • {sourceLocale}
      • {targetLocale}
      • {sourceText}
    • Request body (required): Before configuring the request body, review these parameters: max number of source strings per single request and max number of characters per single source string. The request body supports these placeholders. 
      • If you set the max number of source strings per request to more than one, you'll receive a list of strings. In this case, wrap the {sourceText} variable in square brackets to form a list. 
        Example request body: 
         
        {
  "sourceLanguage": "{sourceLocale}",
          "targetLanguage": "{targetLocale}",
          "content": ["{sourceText}"]
        }
        Example resulting request: 
        {
          "sourceLanguage": "en-US",
          "targetLanguage": "fr-FR",
          "content": ["Text to translate", "Another text to translate"]
        }
      • If you are sending only one string per request, set the max number of source strings to one and send {sourceText} as a single string, not a list. 
        Example request body:  
        {
          "sourceLanguage": "{sourceLocale}",
          "targetLanguage": "{targetLocale}",
          "content": "{sourceText}"
        }
      • Translated text response attribute 'jsonPath' (required): Specify the JSONPath to extract translated text from the response. 
        Example (multiple strings translations): 
         
        {
          "data": {
            "translations": [
              { "translatedText": "Bonjour" },
              { "translatedText": "Salut" },
              { "translatedText": "Bonsoir" }
            ]
          }
        }
        JSON Path: 
        $.data.translations[*].translatedText
        Example (single string translation): 
        {
          "data": {
            "translation": "Bonjour"
          }
        }
        JSON Path: 
        $.data.translation

        You can test your JSONPath using any online JSONPath evaluator, such as this example.  

      • Max amount of source strings per single request (required): number of source strings that the MT/LLM provider supports per single request. This determines how strings are split. 
        Example: A string with 82 characters and a maximum character limit of 40 will be split into multiple parts. If the maximum number of source strings per request is set to one, these parts will be sent as separate requests (or combined, depending on your max amount of source strings per single request setting) 
      • Max amount of characters per single source string
  4. Click Test Integration to verify that the MT Profile is fully functional.
    If successful, a confirmation message will appear. If there's a configuration issue, an error message will be displayed. If the error is unclear, contact your Customer Success Manager or another Smartling representative for assistance. 
  5. Click Save to create the MT Profile. 

What's next? 

The MT Profile is now ready to use for translating your content, whether within the Smartling platform using an MT workflow or MT suggestions in the CAT Tool, or through one of Smartling’s MT integrations to display machine translations directly where needed. Learn more here. 

General information and troubleshooting 

Placeholder descriptions

Placeholder  Description 
{apiKey} Access token/key from the selected credentials.
{sourceLocale} Locale ID of the source language. (Must be a Smartling supported language.) 
{targetLocale} Locale ID of the target language. (Must be a Smartling supported language). 
{sourceText} The text string to be translated.

Retry behavior

All requests for MT in the CAT Tool and Smartling Translate (or any other MT integration) that uses the Common REST API Provider, will not be immediately retried for the following HTTP status codes:

  • 400 (Bad Request)
  • 401 (Unauthorized)
  • 403 (Forbidden)
  • 404 (Not Found)
  • 429 (Too Many Requests)
  • 502 (Bad Gateway)
  • 503 (Service Unavailable)
  • 504 (Gateway Timeout)
  • 200 (OK)

All other status codes will be retried up to three times immediately on the HTTP client level. 

For translation via Smartling jobs (e.g., using an MT workflow with the Common REST API Provider), there are several types of retries and all errors will eventually be retried. 

Troubleshooting missing translations 

If translations are missing from a translation job in Smartling, or if they are not appearing where expected (for example, in the CAT Tool, Smartling Translate, or another MT integration), navigate to the MT Profile page and check for any error notifications. Error notifications are displayed if the MT or AI provider is temporarily unavailable or if the locale pair (source and target locale) is not supported. If the string was translated by the provider, but the translation could not be imported into Smartling due to an error (such as placeholder or tag mismatches, or invalid placeholders or tags), an Issue will be opened for the string. 

Table of Contents