Custom MT Module

This module helps you connect machine translation engines not yet supported by Crowdin. Once you create this kind of app, you’ll be able to pre-translate your content with the connected MT or enable translation suggestions made by it to be shown in the Editor for translators.

Access

You can grant access to this module to one of the following user categories:

For Crowdin:

Only me (i.e., project owner)
All project members
Selected users

For Crowdin Enterprise:

Only organization admins
All users in the organization projects
Selected users

Structure

{
  "modules": {
    "custom-mt": [
      {
        "key": "custom-mt",
        "name": "Custom MT",
        "logo": "/logo.png",
        "url": "/translate",
        "withContext": true,
        "batchSize": 10
      }
    ]
  }
}

Properties

`key`	Type: `string` Required: yes Description: Module identifier within the Crowdin app.
`name`	Type: `string` Required: yes Description: The human-readable name of the module.
`logo`	Type: `string` Required: yes Description: The relative URL to the custom MT’s logo that will be displayed in the Crowdin UI. The recommended resolution is 48x48 pixels.
`url`	Type: `string` Required: yes Description: The relative URL to the content page of the module that will be integrated with Crowdin.
`withContext`	Type: `boolean` Required: no Description: The additional meta data that will be sent along the strings.
`batchSize`	Type: `integer` Required: no Description: The maximum quantity of strings that can be sent to the Custom MT app in one request.
`environments`	Type: `string` Allowed values: `crowdin`, `crowdin-enterprise` Description: Set of environments where a module could be installed. This parameter is needed for cross-product applications.

Communication between Custom MT App and Crowdin

The system sends texts for translation using url and then the app processes the texts and responds back to the system with one of the two possible types of responses: without errors, and with errors.

HTTP request:

https://{AppBaseUrl}/translate/?source=en&target=uk&project_id=727186&jwtToken={yourTokenValue}

Query parameters

`source`	Type: `string` Description: Source language.
`target`	Type: `string` Description: Target language.
`project_id`	Type: `integer` Description: The numeric identifier of a Crowdin project.
`jwtToken`	Type: `string` Description: JWT token used for authorization.
`strings`	Type: `string` Description: Source strings that require translation.

Handling Non-Translatable Elements by Your MT Engine

For strings containing non-translatable elements (e.g., tags, placeholders, etc.), Crowdin replaces these elements with special notranslate tags. This ensures that these elements remain in their original state after the string is translated by the MT engine. Crowdin uses this approach to avoid potential issues that could break exported translation files.

Below you can see the examples of a string before and after the modification.

Here is an example of how a string containing non-translatable elements (tags, placeholders, etc.) looks in Crowdin:

<strong>Task:</strong>

This is how Crowdin modifies the above string before sending it to the MT engine:

<span class="notranslate">0</span>Task:<span class="notranslate">1</span>

Customizing Non-Translatable Elements for Your MT Engine

If your MT engine already has a similar feature but implements it differently from Crowdin, we recommend adjusting the handling of non-translatable elements in your Custom MT app to match your MT engine’s implementation. Specifically, replace Crowdin’s defaults, like

<span class="notranslate">%index%</span>

with do-not-translate elements specific to your MT engine.

Here you can explore an implementation example of do-not-translate elements in Amazon Translate: Using do-not-translate in Amazon Translate.

Handling Translations with Altered Non-Translatable Elements

If the MT engine sends a translation to Crowdin that doesn’t include all tags in their original state or if they are somehow altered (e.g., translated), Crowdin will ignore such translations and won’t save them to the string.

Request to the App from Crowdin for applicationUrl (simple)

Request payload example:

{
  "strings": [
    "Save as...",
    "New file",
    "You received one message.",
    "You received {number} messages."
  ]
}

Request to the App from Crowdin for applicationUrl (extended)

To use the extended request please add the withContext parameter to your Custom MT module.

Request payload example:

{
  "strings": [
    {
      "id": 1,
      "projectId": 727186,
      "fileId": 47047,
      "text": "Save as...",
      "identifier": "save_as",
      "context": "translation Context",
      "maxLength": 15,
      "isHidden": false,
      "isPlural": false,
      "pluralForm": null
    },
36 collapsed lines
    {
      "id": 2,
      "projectId": 727186,
      "fileId": 47047,
      "text": "New file",
      "identifier": "new_file",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": false,
      "pluralForm": null
    },
    {
      "id": 3,
      "projectId": 727186,
      "fileId": 47047,
      "text": "You received one new message.",
      "identifier": "new_message",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": true,
      "pluralForm": "one"
    },
    {
      "id": 3,
      "projectId": 727186,
      "fileId": 47047,
      "text": "You received {number} new messages.",
      "identifier": "new_message",
      "context": "translation Context",
      "maxLength": null,
      "isHidden": false,
      "isPlural": true,
      "pluralForm": "other"
    }
  ]
}

Expected Response from the App (Without errors)

Response payload example:

{
  "data": {
    "translations": [
      "Зберегти як...",
      "Новий файл",
      "Ви отримали одне нове повідомлення.",
      "Ви отримали {number} нових повідомлень."
    ]
  }
}

Expected Response from the App (With errors)

Response payload example:

{
  "error": {
    "message": "Error message from the App or MT engine"
  }
}

The structure of the responses from the app should correspond to the presented examples, otherwise Crowdin will consider them invalid.

Was this page helpful?