API Documentation

ModernMT Enterprise services are available through publicly available REST API that allows you to request translations, manage your memories and check your billing profile.

Api key

In order to use ModernMT Enterprise services you need an api key. If you do not have an api key yet, you can get one here: https://www.modernmt.com/license/buy.

For every API request you have to include an HTTP Header with name MMT-ApiKey and your api key as value.

MMT-ApiKey: 01234567-8901-2345-6789-012345678901

Client Identity

Clients for ModernMT Enterprise services should also specify a few more details when sending requests to ModernMT APIs. These data mainly concern the client identity, and they can be extremely valuable in our support activities to our clients, allowing us to track the traffic from and to a specific client, and letting us immediately intervene in case of necessity. These client identity data should be set as HTTP Headers in the client requests:

  • MMT-Platform: the name of the software that is using ModernMT Enterprise services (example: “MyWonderfulCATTool”).
  • MMT-PlatformVersion: the version of the software that is using ModernMT Enterprise services (example: “2.1.3”).
  • MMT-PluginVersion: the version of the plugin that is being used to call the ModernMT Enterprise services APIs (example: “1.1”).

The ideal requests, therefore, looks like this (using curl for simplicity):

curl -H "MMT-ApiKey:<my_api_key>" \
     -H "MMT-PluginVersion:<my_plugin_version>" \
     -H "MMT-Platform:<my_platform_name>" \
     -H "MMT-PlatformVersion:<my_platform_version>" \
     https://api.modernmt.com/...

Endpoints

A REST endpoint consists of an HTTP method and a path to the resource. Usually the HTTP method describes the action, while the path identifies the resource or the service you are interacting with.

There can be cases in which the caller is limited in the use of HTTP methods for tecnical reasons or by HTTP protocol limitations (i.e. max allowed GET request length). For this reason ModernMT allows you to use any actual HTTP method, while separately declare the REST API method through the X-HTTP-Method-Override header.

For example, it is allowed to request a translation with an HTTP POST request like this:

curl -X POST \
     -H 'X-HTTP-Method-Override: GET' \
     -H 'MMT-ApiKey: <your_api_key>' \
    'https://api.modernmt.com/translate?source=en&target=it&q=Hello'

Translation

Memory

User and Billing

General aspects

All APIs responses have a common structure that allows the user to quickly understand if the request returned a valid output or if an error occurred. This is the positive response wireframe:

{
      "data": "...request specific data...",
      "status": 200
}

In case of error, the API will send back a response like the following:

{
      "error": {
          "message": "Missing parameter text",
          "type": "ParameterParsingException"
      },
      "status": 400
}

Error Codes

In an error response you can always find error.message that contains a text that explains the error and error.type that is the id of the error.

The ModernMT API uses the HTTP status codes to identify which type of error has occurred. The status field in the response is always the same as the HTTP status code, it is reported twice just for convenience.

  • Status 2xx: OK - The API returned successfully.
  • Status 4xx: CLIENT ERROR - The API has detected a problem with the request made by the caller (a missing parameter or a nonexistent API).
  • Status 5xx: SERVER ERROR - The API has failed unexpectedly for an internal server error.

Input format

MMT support XML input type for translations. XML tags are extracted from the source text, and re-inserted in the translation in the right position, based on the translation alignments.

During the pre-processing:

  • XML Tags are identified and extracted from the text.
  • Pure text is then de-escaped: XML entities are replaced with the actual literal (e.g. &lt; is replaced with char <).

The text is then translated by the decoder. During the post-processing step:

  • Text is then escaped following the XML conventions. Characters <, > and & are escaped in &lt;, &gt; and &amp;.
  • XML Tags are positioned in the translation based on the alignments. Tag’s attributes are kept untouched.

See the following example:

  • Input: You&apos;ll see the <div id="example-div">example</div>!
  • Preprocessed: You 'll see the example !
  • Translation: Vedrai l' esempio !
  • Postprocessed: Vedrai l'<div id="example-div">esempio</div>!