API Documentation

For the cloud-based ModernMT API, see https://www.modernmt.com/api/

ModernMT comes with built in REST API that allows the user to control every feature of MMT via a simple and powerful interface.

Methods

Translation

• GET /translate - Translate text
• GET /context-vector - Context Vector guessing from raw text

Memory

• POST /memories - Create a new empty memory
• GET /memories/:id - Get the metadata of a memory given its id
• PUT /memories/:id - Update the metadata of a memory given its id
• PUT /memories/:id/corpus - Add parallel text to memory corpus
• DELETE /memories/:id - Remove a memory from the system
• GET /memories - List all memories in the system
• GET /memories/imports/:id - Retrieve the status of an import job

Tags Projection

• GET /tags-projection - Guess the position of the tags in the provided translation

Admin

• GET / - Get the server metadata, such as the build number, version number and cluster topology.

General Notes

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 &quot;, &apos;, &lt;, &gt; and &amp;.
• XML Tags are positioned in the translation based on the alignments. Tag's content is 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&apos;<div id="example-div">esempio</div>!