---
title: "API based translation"
slug: "api-based-translation"
status: "new"
updated: 2025-05-29T09:01:57Z
published: 2025-05-29T09:01:57Z
canonical: "support.whatfix.com/api-based-translation"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.whatfix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API based translation

API-based translation is an asynchronous method that uses API requests to send and receive translated content.

This method sends text strings or JSON files to the third-party translation service and receives the translated content in the same API response. This is particularly beneficial for smaller translation tasks or when real-time processing is needed.

Expand the following accordions to successfully integrate a custom translation tool:

> [!WARNING]
> Note:
> 
> The integration setup for the following steps uses **Microsoft Azure** as an example. Based on your requirements and the tool of your choice, setup the integration accordingly.

****Step 1: Add a custom tool for API based translation****

Whatfix enables you to add a custom translation tool based on your requirements and internal processes.

Use the following steps to add a translation tool based on an API request:

1. On the Whatfix Guidance dashboard, click **Settings**.  

![ia_settings_without_auto_testing](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/ia_settings_without_auto_testing.png)

1. Click **Translation tools**.

![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_click_settings_translation_tools(3).jpg)
2. On the **Translation tools** page, click the **Add** icon. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_add_icon.jpg)
3. In the **Integrating with Custom tool** dialog box, enter the name of the tool, and then select **API** as the translation method. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/translation_tools_name_api_based.jpg)
4. Click **Continue**. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/translation_tools_continue.jpg)

****Step 2: Map languages for API based translation****

Translation tools use codes to distinguish languages and translate content. In the **Map Languages** section, configure language codes to set the to and from language. You must map the language code used in the translation tool with the language supported by Whatfix. For example, Fr: fr (french) and De: de (German).

> [!WARNING]
> Note:
> 
> - You must also map the **Primary Language** used to create Whatfix content. Otherwise, Whatfix cannot detect and send the content for translation.
> - Once you have integrated the tool, add languages directly from the **Translations** page in the **Configurations** section: ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/translation_configurations_map _languages.jpg)

After you have added a translation tool, use the following steps to add languages and map them between Whatfix and the custom translation tool:

1. In the **Map Languages** section, use the dropdown and select the input language. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_map_languages_input_lang.jpg)
2. Enter the language code as recognized by the translation tool. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_map_languages_input_lang_code.jpg)
3. To map other languages, click **+ Add language code**. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_map_languages_input_add_lang_code.jpg)
4. Select the input language and add the language code. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_map_languages_add_lang_code.jpg)

****Step 3: Convert Whatfix data to a format accepted by the custom tool****

Whatfix content must be converted into a format so that the translation tool can receive and interpret the data. This includes to and from language, translation attributes and other details to uniquely identify the content and the fields in the content that require translation.

Use the following steps to convert Whatfix data to a format accepted by the custom tool:

> [!WARNING]
> Note:
> 
> Refer to the [Translation Tool Guidelines](/studio/docs/translation-tool-guidelines) to learn about Javascript and Request parameters while configuring the steps for the custom translation tool.

1. In the **Convert Whatfix data to format accepted by the custom tool** section, enter a **Description** (Optional). By default, the **Configuration type** is set to **Javascript**. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_2_desc_config.jpg)
2. In the **Script** field, enter the Javascript code to convert Whatfix data into a format accepted by the custom translation tool. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_2_script.jpg)

Here’s an example Javascript code for Microsoft Azure:

```javascript
function convertToMicrosoftTranslationInput(original_data) {
    var inputForMs = [];
    for (var i = 0; i < original_data.length; i++) {
        var item = original_data[i];
        inputForMs.push({
            "Text": item.value
        });
    }
    return inputForMs;
}

var microsoftTranslationInput = convertToMicrosoftTranslationInput(attributes.translationStrings);
// Here we can see that strings that need to be translated can be accessed by attributes.translationStrings
output.data = microsoftTranslationInput;
```

> [!WARNING]
> Note:
> 
> The JS Script code editor only supports versions earlier than ES6. For more information about specifying variables and parameters, see [Translation Tool Guidelines](/studio/docs/translation-tool-guidelines).

The preceding Javascript code reads the translationStrings from Whatfix, formats it into a structure that Microsoft accepts, and saves the result in a variable called `output.data` for the next step.

****Step 4: Configure API Request****

This step enables you to request translated content from the custom translation tool through an API request.

Use the following steps to configure the API request:

1. In the **Configure Custom tool** section, enter a **Description** (Optional) and select the **Configuration type.** Choose either **Javascript** or **Request** type. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_3_desc_config_type.jpg)

> [!WARNING]
> Note:
> 
> Refer to [Translation Tool Guidelines](/studio/docs/translation-tool-guidelines) to learn about Javascript and Request parameters while configuring the steps for the custom translation tool.

Based on the **Configuration typ**e, perform the steps in the following accordion:

****Request****

A. In the **Method** dropdown, select **POST.**

![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_3_req_method.jpg)

B. Enter the **URL**.

![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_3_req_url.jpg) Example URL:

```plaintext
https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=${attributes.targetLocale}&from=${attributes.sourceLocale}&textType=html
// Here we can see that in order to access source and target locale we are using attributes.sourceLocale , attributes.targetLocale
```

C. Specify parameter details in the **Headers** field. Due to security reasons, click the **Unhide** icon and then add the Headers.

![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_3_req_headers.jpg)

Here’s an example code for **Headers**:

```javascript
{
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY",
    "Ocp-Apim-Subscription-Region": "Global"
}
```

**Note**: You must specify the **Subscription-Key** for the custom tool.

****Javascript****

In the **Script** field, enter the Javascript code to request translated content from the custom translation tool. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_2_script.jpg)

#### Additional Configurations

In certain scenarios, based on the custom tool, additional configuration steps might be required to receive content. Use the **+ Add configuration** icon to provide additional steps for the API request.![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/translation_tools_3_add_configuration.jpg)

Similar to the steps highlighted above, enter the details in the **Configuration 2** section: ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/translation_tools_3_add_configuration_2.jpg)

****Step 5: Convert the Format from Custom Tool to Whatfix Data****

The translated content received from the translation tool needs to be restructured to align with Whatfix's data format.

Use the following steps to convert the format from the custom translation tool to Whatfix data:

1. In the **Convert format from custom tool to Whatfix data** section, enter a **Description** (Optional). By default, the **Configuration type** is set to **Javascript**. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_4_desc_type.jpg)
2. In the **Script** field, enter the Javascript code to convert the format from the custom tool to Whatfix accepted format. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_2_script.jpg) Here’s an example Javascript code:

```javascript
function mergeTranslatedValues(original_data, translated_data) {
    var result = [];
    for (var i = 0; i < original_data.length; i++) {
        var originalItem = original_data[i];
        var translatedItem = translated_data[i];
        result.push({
            key: originalItem.key,
            value: translatedItem.translations[0].text
        });
    }
    return result;
}

var mergedData = mergeTranslatedValues(attributes.translationStrings, input);
// Output of previous step can be accessed by using input keyword
output.data = mergedData;
```

The preceding Javascript code merges the translated text from Microsoft Azure with the original keys from Whatfix, and can display the translated text correctly.
3. Click **Save**. ![](https://cdn.document360.io/a268766e-d74d-4619-9613-e2472f809ffb/Images/Documentation/db_translation_tools_save.jpg)

To complete the integration process, [activate the custom integration tool](/studio/docs/manage-the-custom-translation-tool) in the **Translation tools** page.

An API call, or API request, is a message sent to a server to request data or a service from an Application Programming Interface (API). APIs are a set of rules and protocols that enable software programs to communicate with each other.