Introduction

BASE URL

https://api.modernmt.com/

CLIENT LIBRARIES

cURL

Node.js

Python

Go

Java

.NET

PHP

By default, the documentation demonstrates using cURL to interact with the API over HTTPS. Select one of our official client libraries to see examples in code.

npm i modernmt # or yarn add

# browser
<script src="https://unpkg.com/modernmt"></script>
pip3 install modernmt
go get github.com/modernmt/modernmt-go
# maven
<dependency>
<groupId>com.modernmt</groupId>
<artifactId>modernmt-java</artifactId>
<version>1.5.0</version>
</dependency>

# gradle
compile "com.modernmt:modernmt-java:1.5.0"
dotnet add package modernmt-dotnet
composer require modernmt/modernmt-php

ModernMT Enterprise services are available through a public REST API that allows you to request translations and manage your memories.

To workaround some HTTP methods limitations ModernMT recommends to send POST requests and separately declare the method through the X-HTTP-Method-Override. This technique is present in this documentation’s cURL examples and libraries.

Authentication

AUTHENTICATION

curl -H "MMT-ApiKey: YOUR_API_KEY" ...
import {ModernMT} from "modernmt";

const mmt = new ModernMT("YOUR_API_KEY")
from modernmt import ModernMT

mmt = ModernMT("YOUR_API_KEY")
import (
    "github.com/modernmt/modernmt-go"
)

mmt := modernmt.Create("YOUR_API_KEY")
import com.modernmt.ModernMT;

ModernMT mmt = new ModernMT("YOUR_API_KEY");
using ModernMT;

var mmt = new ModernMTService("YOUR_API_KEY");
require "./vendor/autoload.php";

use ModernMT\ModernMT;

$mmt = new ModernMT("YOUR_API_KEY");

The ModernMT API uses API keys to authenticate requests. You can view and manage your API key in the account Dashboard.

For every API request you have to include an HTTP header named MMT-ApiKey which contains your API key as value. API requests without this header will fail.

The API key is unique and identifies you, so be sure to keep it secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, and so forth. If you accidentally shared your API key or suspect that it has been stolen, you can reset it from the account Dashboard. This operation will generate a new API key and will invalidate the previous one.

To retrieve information about the license you can use the /users/me endpoint or the "me" method in libraries.

Client Identity

CLIENT IDENTITY

curl -H "MMT-ApiKey: YOUR_API_KEY" -H "MMT-Platform: simple-cat-tool" -H "MMT-PlatformVersion: 1.2.8" ...
import {ModernMT} from "modernmt";

const mmt = new ModernMT("YOUR_API_KEY", "simple-cat-tool", "1.2.8")
from modernmt import ModernMT

mmt = ModernMT("YOUR_API_KEY", "simple-cat-tool", "1.2.8")
import (
    "github.com/modernmt/modernmt-go"
)

mmt := modernmt.CreateWithIdentity("YOUR_API_KEY", "simple-cat-tool", "1.2.8")
import com.modernmt.ModernMT;

ModernMT mmt = new ModernMT("YOUR_API_KEY", "simple-cat-tool", "1.2.8");
using ModernMT;

var mmt = new ModernMTService("YOUR_API_KEY", "simple-cat-tool", "1.2.8");
require "./vendor/autoload.php";

use ModernMT\ModernMT;

$mmt = new ModernMT("YOUR_API_KEY", "simple-cat-tool", "1.2.8");

Clients which use ModernMT API can specify additional identity information using the following headers:

Those data are optional but can be extremely valuable in our support activities, allowing us to track the traffic of a specific client, and letting us immediately intervene in case of necessity, therefore we recommend to include them in every API request.

Session

In ModernMT a translation work session (hereinafter simply "session") refers to a translation job that is carried out by a single human translator and/or reviewer.

Specifically, a translation job is viewed as a chronologically ordered and conceptually connected sequence of sentence-translation pairs produced by the identified translator.

Sessions are the way to leverage ModernMT document-level adaptation during the translation.

It differs from standard ModernMT adaption, focusing on enhancing translation quality by highly adapting to the context of the specific document being translated as more sentence-translation pairs relevant to the specific job are gathered over time.

To obtain the best adaptation results, it is recommended to generate a separate session id for each job-translator pair (e.g. session 1 for translator T-A translating document B, session 2 for translator T-A translating doc C, session 3 for translator T-B translating document D and so on). In case of multiple translators working on the same translation job, it is recommended to use a separate session id for each of them.

MT Glossary

A glossary, in the context of Machine Translation, is a tool that facilitates the consistent translation of customer-specific terminologies, giving advanced control over the terms used.

Glossaries can be highly useful in the following scenarios:

However, it's also important to note which terms are less suitable for MT glossaries, including:

To maximize the efficiency and accuracy of MT glossaries, it's crucial to select suitable terms and understand the limitations of this tool. Similarly, we strongly advise against the use of elements like stopwords as glossary terms unless absolutely confident.

Glossary file structure

A glossary, at its core, is a text document that contains corresponding terms in multiple languages. ModernMT supports both unidirectional glossaries that define the required translation between a pair of source and target languages, and glossaries of equivalent terms that denote the same term across different languages.

The total number of terms across all languages combined should not exceed 10.4 million (10,485,760) UTF-8 bytes = 10 MiB.

By default, ModernMT manages glossary matches in a case-sensitive manner (e.g. the glossary term Translated will match the sentence Translated is a company but not translated is a company). Nonetheless, ModernMT also supports case-insensitive matching. The type of matching can be chosen at translation time.

ModernMT currently supports glossary files in CSV format.

Unidirectional glossary

A unidirectional glossary essentially functions as a dictionary that maps a term from a source language to its designated translation in the target language.

The CSV file must consist of two columns: the first column represents the source term and the second column signifies the associated translation.

The file's initial row acts as a header that denotes the language code (ISO 639-1) for each respective column (any language present in the Languages section is valid). No additional columns have to be inserted for the file to be valid.

No empty values are allowed.

Here's an example of a correctly formatted unidirectional file:

en it
test prova
Translated Translated

Utilizing this glossary would ensure that the English word test is consistently translated to prova in Italian. However, the reverse translation is not enforced (as the glossary is unidirectional).

Equivalent terms glossary

A glossary of equivalent terms essentially works like a multi-lingual dictionary, providing corresponding terms across all the specified languages.

The CSV file must be composed of multiple columns: the first column must contain the tuid (a string identifier), while the remaining columns should represent the different languages that the file includes.

The file's initial row acts as a header that denotes the tuid followed by the language code (ISO 639-1) for each respective column (any language present in the Languages section is valid). No additional columns have to be inserted for the file to be valid.

Empty values are permissible for fields other than tuid, but each row must have at least two non-empty non-tuid fields.

The tuid serves as a unique identification for each group of equivalent terms in the glossary. It is required for updating specific entries.

Here's an example of a correctly formatted equivalent terms glossary file:

tuid en it fr es
1 test prova prueba
2 Translated Translated Translated Translated
3 ModernMT ModernMT

Utilizing this glossary would ensure that any term in a particular row is consistently translated into the right term in another language, provided the term is not empty (e.g. translating ModernMT from it to es would result in the application of the ModernMT glossary term, while translating it to fr wouldn't result in the application of the glossary, since no entry is present for the fr column on that glossary row).

Response and Errors

SUCCESS RESPONSE

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

ERROR RESPONSE

{
  "status": 400,
  "error": {
    "type": "UnsupportedLanguageException",
    "message": "Language pair not supported: en > xd"
  }
}

ModernMT uses conventional HTTP response codes to indicate the success or failure of an API request. The status code is always included in the response "status" field.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (a required parameter was omitted, the requested resource does not exist, etc.). Codes in the 5xx range indicate an error in ModernMT’s servers.

In case of success, the response includes a "data" field which contains the request result. In case of failure, the response includes an "error" field that contains the failure type and an explanatory message. Official libraries methods will return the data field content or throw an exception in case of failure.

Languages

ModernMT supports a wide variety of languages. Translations from any language to any language in this list are supported. The list is updated as new languages are added. The list of supported language codes can be retrieved using the languages API.

A
Acehnese - ace
Afrikaans - af
Akan - ak
Albanian - sq
Amharic - am
Arabic - ar
Armenian - hy
Assamese - as
Asturian - ast
Awadhi - awa
Ayacucho Quechua - quy
Aymara, Central - ayr
Azerbaijani - az
Azerbaijani, Northern - azj
Azerbaijani, Southern - azb

B
Balinese - ban
Bambara - bm
Banjar - bjn
Bashkir - ba
Belarusian - be
Bemba - bem
Bengali - bn
Bhojpuri - bho
Bosnian - bs
Buginese - bug
Bulgarian - bg

C
Catalan - ca
Cebuano - ceb
Chhattisgarhi - hne
Chinese (Simplified) - zh-CN
Chinese (Traditional) - zh-TW
Chokwe - cjk
Crimean Tatar - crh
Croatian - hr
Czech - cs

D
Danish - da
Dari - prs
Dimli - diq
Dinka, Southwestern - dik
Dutch - nl
Dyula - dyu
Dzongkha - dz

E
English - en
Esperanto - eo
Estonian - et
Ewe - ee

F
Faroese - fo
Fijian - fj
Finnish - fi
Fon - fon
French - fr
Friulian - fur

G
Galician - gl
Ganda - lg
Georgian - ka
German - de
Greek - el
Guarani - gn
Gujarati - gu
H
Haitian - ht
Halh Mongolian - khk
Hausa - ha
Hebrew - he
Hindi - hi
Hungarian - hu

I
Icelandic - is
Igbo - ig
Iloko - ilo
Indonesian - id
Irish - ga
Italian - it

J
Japanese - ja
Javanese - jv
Jingpho - kac

K
Kabiyè - kbp
Kabuverdianu - kea
Kabyle - kab
Kamba - kam
Kannada - kn
Kanuri, Central (Latin script) - knc
Kashmiri (Arabic script) - kas
Kashmiri (Devanagari script) - ks
Kazakh - kk
Khmer - km
Kikuyu - ki
Kimbundu - kmb
Kinyarwanda - rw
Kongo - kg
Korean - ko
Kurdish, Central - ckb
Kurdish, Northern - kmr
Kyrgyz - ky

L
Lao - lo
Latgalian - ltg
Latin - la
Latvian - lv
Ligurian - lij
Limburgish - li
Lingala - ln
Lithuanian - lt
Lombard - lmo
Luba-Kasai - lua
Luo - luo
Luxembourgish - lb

M
Macedonian - mk
Magahi - mag
Maithili - mai
Malagasy - mg
Malay - ms
Malayalam - ml
Maltese - mt
Manipuri - mni
Maori - mi
Marathi - mr
Minangkabau - min
Mizo - lus
Mongolian (Traditional) - mn
Mossi - mos
Myanmar (Burmese) - my
N
Nepali - ne
Nigerian Fulfulde - fuv
Norwegian (Bokmål) - nb
Norwegian (Nynorsk) - nn
Nuer - nus
Nyanja - ny

O
Occitan - oc
Odia (Oriya) - or
Oromo, West Central - gaz

P
Pangasinan - pag
Papiamento - pap
Pashto, Southern - pbt
Pastho - ps
Persian, Western - pes
Plateau Malagasy - plt
Polish - pl
Portuguese (Brazil) - pt-BR
Portuguese (Portugal) - pt-PT
Punjabi - pa

R
Romanian - ro
Rundi - rn
Russian - ru

S
Samoan - sm
Sango - sg
Sanskrit - sa
Santali - sat
Sardinian - sc
Scots Gaelic - gd
Serbian (Cyrillic) - sr-Cyrl
Serbian (Latin) - sr-Latn
Shan - shn
Shona - sn
Sicilian - scn
Silesian - szl
Sindhi - sd
Sinhala - si
Slovak - sk
Slovenian - sl
Somali - so
Sotho, Northern - nso
Sotho, Southern - st
Spanish - es-ES
Spanish (Latin America) - es-419
Standard Latvian - lvs
Standard Malay - zsm
Sundanese - su
Swahili - sw
Swati - ss
Swedish - sv
T
Tagalog - tl
Tajik - tg
Tamasheq - taq
Tamazight, Central Atlas - tzm
Tamil - ta
Tatar - tt
Telugu - te
Thai - th
Tibetan - bo
Tigrinya - ti
Tok Pisin - tpi
Tosk Albanian - als
Tsonga - ts
Tswana - tn
Tumbuka - tum
Turkish - tr
Turkmen - tk
Twi - tw

U
Ukrainian - uk
Umbundu - umb
Urdu - ur
Uyghur - ug
Uzbek, Northern - uzn

V
Venetian - vec
Vietnamese - vi

W
Waray (Philippines) - war
Welsh - cy
Wolof - wo

X
Xhosa - xh

Y
Yiddish, Eastern - ydd
Yoruba - yo

Z
Zulu - zu

Endpoints

Translation

Supported languages

GET /translate/languages

curl "https://api.modernmt.com/translate/languages"
const languages = await mmt.listSupportedLanguages()
languages = mmt.list_supported_languages()
languages, err := mmt.ListSupportedLanguages()
List<String> languages = mmt.listSupportedLanguages();
var languages = mmt.ListSupportedLanguages();
$languages = $mmt->list_supported_languages();

RESPONSE

{
  "data": [...],
  "status": 200
}

Gives the list of supported language codes (ISO 639-1) for translation.

Request parameters

None.

Result

Returns an array which contains supported language codes.

Language detection

GET /translate/detect - SINGLE TEXT

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"q":"buongiorno"}' \
    "https://api.modernmt.com/translate/detect"
const language = await mmt.detectLanguage("buongiorno")
language = mmt.detect_language("buongiorno")
language, err := mmt.DetectLanguage("buongiorno", "")
DetectedLanguage language = mmt.detectLanguage("buongiorno");
var language = mmt.DetectLanguage("buongiorno");
$language = $mmt->detect_language("buongiorno");

RESPONSE

{
  "status": 200,
  "data": {
    "detectedLanguage": "it",
    "billedCharacters": 0
  }
}

GET /translate/detect - MULTIPLE TEXTS

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"q":["buongiorno", "goodmorning"]}' \
    "https://api.modernmt.com/translate/detect"
const languages = await mmt.detectLanguage(["buongiorno", "goodmorning"])
languages = mmt.detect_language(["buongiorno", "goodmorning"])
languages, err := mmt.DetectLanguage([]string{"buongiorno", "goodmorning"}, "")
List<DetectedLanguage> languages = mmt.detectLanguage(Arrays.asList("buongiorno", "goodmorning"));
var languages = mmt.DetectLanguage(new List<string>{"buongiorno", "goodmorning"});
$languages = $mmt->detect_language(["buongiorno", "goodmorning"]);

RESPONSE

{
  "status": 200,
  "data": [
    {
      "detectedLanguage": "it",
      "billedCharacters": 0
    },
    {
      "detectedLanguage": "en",
      "billedCharacters": 0
    }
  ]
}

Allows to detect the language of an input text or a list of texts.

Request parameters

Name Description
q The input text or an array of texts. The text may include one or multiple sentences. Texts languages are returned in the same order as they are requested. The maximum length of the array is 128
format The input text format, see tags handling. Options currently available: text/plain, text/xml, text/html and application/xliff+xml. Default is auto-detected

Result

The language detection API returns a JSON (or an array of JSON if multiple texts were provided, in the given order) which includes the following fields:

Name Description
billedCharacters The amount of billed characters
detectedLanguage The detected language code (ISO 639-1)

Translate text

GET /translate - SINGLE TEXT

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source":"en", "target":"it", "q":"Hello world."}' \
    "https://api.modernmt.com/translate"
const translation = await mmt.translate("en", "it", "Hello world.")
translation = mmt.translate("en", "it", "Hello world.")
translation, err := mmt.Translate("en", "it", "Hello world", nil)
Translation translation = mmt.translate("en", "it", "Hello world.");
var translation = mmt.Translate("en", "it", "Hello world.");
$translation = $mmt->translate("en", "it", "Hello world.");

RESPONSE

{
  "status": 200,
  "data": {
    "translation": "Ciao mondo.",
    "billedCharacters": 12,
    "characters": 12
  }
}

GET /translate - MULTIPLE TEXTS

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "en", "target":"it", "q":["Hello world.", "This is a test"]}' \
    "https://api.modernmt.com/translate"
const translations = await mmt.translate("en", "it", ["Hello world.", "This is a test"])
translations = mmt.translate("en", "it", ["Hello world.", "This is a test"])
translations, err := mmt.TranslateList("en", "it", []string{"Hello world.", "This is a test"}, nil)
List<Translation> translations = mmt.translate("en", "it", Arrays.asList("Hello world.", "This is a test"));
var translations = mmt.Translate("en", "it", new List<string>{"Hello world.", "This is a test"});
$translations = $mmt->translate("en", "it", ["Hello world.", "This is a test"]);

RESPONSE

{
  "status": 200,
  "data": [
    {
      "translation": "Ciao mondo.",
      "billedCharacters": 12,
      "characters": 12
    },
    {
      "translation": "Questo è un test",
      "billedCharacters": 14,
      "characters": 14
    }
  ]
}

GET /translate - HINTS

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "it", "target":"en", "q":"Dì il mio nome.", "hints":"37790"}' \
    "https://api.modernmt.com/translate"
const translation = await mmt.translate("it", "en", "Dì il mio nome.", [37790])
translation = mmt.translate("it", "en", "Dì il mio nome.", [37790])
translation, err := mmt.TranslateAdaptive("it", "en", "Dì il mio nome.", []int64{37790}, "", nil)
Translation translation = mmt.translate("it", "en", "Dì il mio nome.", new long[]{37790});
var translation = mmt.Translate("it", "en", "Dì il mio nome.", new long[]{37790});
$translation = $mmt->translate("it", "en", "Dì il mio nome.", [37790]);

RESPONSE

{
  "status": 200,
  "data": {
    "translation": "Say my name.",
    "billedCharacters": 15,
    "characters": 15,
    "contextVector": "37790:1"
  }
}

GET /translate - GLOSSARIES

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "en", "target":"it", "q":"I loved the movie: The perks of being a wallflower.",
    "glossaries":"37787,37784,37790,37791"}' \
    "https://api.modernmt.com/translate"
const translation = await mmt.translate("en", "it", "I loved the movie: The perks of being a wallflower.", undefined, undefined, {
    glossaries: [37787, 37784, 37790, 37791]
});
translation = mmt.translate("en", "it", "I loved the movie: The perks of being a wallflower.", options={
    "glossaries": [37787, 37784, 37790, 37791],
})
options := modernmt.TranslateOptions{
    Glossaries: []int64{37787, 37784, 37790, 37791},
}
translation, err := mmt.Translate("en", "it", "I loved the movie: The perks of being a wallflower.", &options)
TranslateOptions opts = new TranslateOptions();
opts.setGlossaries(new long[]{ 37787, 37784, 37790, 37791 });

Translation translation = mmt.translate("en", "it", "I loved the movie: The perks of being a wallflower.", opts);
var options = new TranslateOptions();
options.SetGlossaries(new long[] { 37787, 37784, 37790, 37791 });

var translation = mmt.Translate("en", "it", "I loved the movie: The perks of being a wallflower.", options);
$translation = $mmt->translate("en", "it", "I loved the movie: The perks of being a wallflower.", null, null, [
    'glossaries' => [37787, 37784, 37790, 37791],
]);

RESPONSE

{
  "status": 200,
  "data": {
    "translation": "Ho adorato il film: Noi siamo infinito.",
    "billedCharacters": 34,
    "characters": 34,
  }
}

GET /translate - OPTIONS

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "en", "target":"it", "q":"The weather is good today", "alt_translations": 2}' \
    "https://api.modernmt.com/translate"
const translation = await mmt.translate("en", "it", "The weather is good today", undefined, undefined, {
    altTranslations: 2
})
translation = mmt.translate("en", "it", "The weather is good today", options={
    "alt_translations": 2
})
translation, err := mmt.Translate("en", "it", "The weather is good today", &modernmt.TranslateOptions{
    AltTranslations: 2,
})
TranslateOptions opts = new TranslateOptions();
opts.setAltTranslations(2);
Translation translation = mmt.translate("en", "it", "The weather is good today", opts);
var translation = mmt.Translate("en", "it", "The weather is good today", new TranslateOptions
{
    AltTranslations = 2
});
$translation = $mmt->translate("en", "it", "The weather is good today", null, null, [
    'alt_translations' => 2
]);

RESPONSE

{
  "status": 200,
  "data": {
    "translation": "Il tempo è bello oggi",
    "billedCharacters": 25,
    "characters": 25,
    "altTranslations": [
      "Il tempo è buono oggi",
      "Oggi il tempo è bello"
    ]
  }
}

GET /translate - MASK PROFANITIES

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "en", "target":"it", "q":"Fuck you", "mask_profanities": true}' \
    "https://api.modernmt.com/translate"
const translation = await mmt.translate("en", "it", "Fuck you", undefined, undefined, {
    maskProfanities: true
})
translation = mmt.translate("en", "it", "Fuck you", options={
    "mask_profanities": True
})
translation, err := mmt.Translate("en", "it", "Fuck you", &modernmt.TranslateOptions{
    MaskProfanities: true,
})
TranslateOptions opts = new TranslateOptions();
opts.setMaskProfanities(true);
Translation translation = mmt.translate("en", "it", "Fuck you", opts);
var translation = mmt.Translate("en", "it", "Fuck you", new TranslateOptions
{
    MaskProfanities = true
});
$translation = $mmt->translate("en", "it", "Fuck you", null, null, [
    'mask_profanities' => true
]);

RESPONSE

{
  "status": 200,
  "data": {
    "translation": "V********o",
    "billedCharacters": 8,
    "characters": 8,
    "detectedProfanities": true
  }
}

Allows to translate an input text or a list of texts.

Request parameters

Name Description
source The language code (ISO 639-1) of the source text(s). If omitted, ModernMT will attempt to detect the source language automatically and return it within the response
target The language code (ISO 639-1) to use for translation of the input text(s)
q The input text or an array of texts to be translated. The text may include one or multiple sentences. Translations are returned in the same order as they are requested. If no source is provided, the array can include texts in different languages. The maximum length of the array is 128. See the note about tags handling
context_vector The context vector to use for the translation of the input text(s). This is necessary for adaptation
hints The hints for the context vector. If context_vector is omitted, it will be created automatically including those memories only
glossaries The glossaries to use for the translation of the input text(s)
ignore_glossary_case When handling glossaries for translation of the input text(s), ModernMT applies them in a case sensitive manner. This boolean parameter can alter this default behavior. True will apply the specified glossaries in a case-insensitive fashion, false will maintain case sensitivity in glossary application
priority The priority of the translation request. It can be normal or background. Default value depends on your pricing plan
multiline Given a long text, ModernMT automatically decides if to split the text in sub-sentences in order to provide a better translation result. This boolean parameter can force this behavior. True will always attempt to split, false disables it
timeout Aborts the request if the translation is not completed in the given milliseconds
format The input text format, see tags handling. Options currently available: text/plain, text/xml, text/html and application/xliff+xml. Default is auto-detected
alt_translations Include several alternative translations in the response. This parameter specifies the maximum number of alternative translations to be produced (the actual number can be equal or less than the specified value), the default is 0 (disabled) and the maximum value is 32. Please note that the usage of this parameter may impact response time
session The session identifier, see session
mask_profanities A boolean which indicates if ModernMT has to detect and mask profanities in translation. Default is false

Result

The translate API returns a JSON representation of the translation (or an array of JSON representations if multiple texts were provided, in the given order). The JSON has the following structure:

Name Description
translation The text translated into the target language
contextVector The context vector effectively used in the translation, which has hints applied and eventually non-existing memories provided filtered out. This field is omitted if no context vector or hints are provided in the request, or if they include only non-existing memories
characters The amount of characters of the input text
billedCharacters The amount of billed characters
detectedLanguage The source language code (ISO 639-1) detected automatically. This field is omitted if the source language code is provided in the request
altTranslations An array of alternative translations, sorted by estimated quality from highest to lowest. This field is omitted if alt_translations is not provided in the request, or if it is equal to 0
detectedProfanities A boolean which indicates if ModernMT detected profanities in translation. This field is omitted if mask_profanities is not provided in the request, or if it is equal to false

Tags handling

ModernMT supports tags handling for translations. Tags are extracted from the input text(s) and then re-inserted in the translation in the right position. Tag’s attributes are kept untouched.

Pre-processing:

Post-processing:

Example:

Batch BETA

GET /translate/batch

curl -X POST \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    -H "x-idempotency-key: b7f04ab3-68d6-47c0-8eea-0743a710b620" \
    --data '{"source":"en", "target":"it", "q":"Hello world.",
    "webhook":"https://example.com", "metadata": {"timestamp":1676023422231}}' \
    "https://api.modernmt.com/translate/batch"
// --- Request ---
const webhook = 'https://example.com';
const enqueued = await mmt.batchTranslate(webhook, 'en', 'it', 'Hello world.', undefined, undefined, {
    metadata: {
        timestamp: Date.now()
    },
    idempotencyKey: 'b7f04ab3-68d6-47c0-8eea-0743a710b620'
})

// --- Callback ---
// body must be an object or a json string
// signature must be the value of 'x-modernmt-signature' header
const batchTranslation = await mmt.handleCallback(body, signature)
# --- Request ---
webhook = 'https://example.com'
enqueued = mmt.batch_translate(webhook, 'en', 'it', 'Hello world.', options={
    'metadata': {
        'timestamp': time.time()
    },
    'idempotency_key': 'b7f04ab3-68d6-47c0-8eea-0743a710b620'
})

# --- Callback ---
# body must be a dictionary or a json string
# signature must be the value of 'x-modernmt-signature' header
data, metadata = mmt.handle_callback(body, signature)
// --- Request ---
options := modernmt.TranslateOptions{
    Metadata: metadata{
        time.Now().UnixNano() / int64(time.Millisecond), // Timestamp
    },
    IdempotencyKey: "b7f04ab3-68d6-47c0-8eea-0743a710b620",
}

webhook := "https://example.com"
enqueued, err := mmt.BatchTranslate(webhook, "en", "it", "Hello world.", &options)

// --- Callback ---
// body must be a slice of bytes
// signature must be the value of 'x-modernmt-signature' header
metadata := &metadata{}
data, err := mmt.HandleTranslateCallbackWithMetadata(body, signature, &metadata)
// --- Request ---
TranslateOptions opts = new TranslateOptions();
opts.setMetadata(new Metadata()); // in our example has a timestamp field
opts.setIdempotencyKey("b7f04ab3-68d6-47c0-8eea-0743a710b620");

String webhook = "https://example.com";
boolean enqueued = mmt.batchTranslate(webhook, "en", "it", "Hello world.", opts);

// --- Callback ---
// body must be an Object or a json string
// signature must be the value of 'x-modernmt-signature' header
// the third parameter is the class of metadata object (if any)
BatchTranslation batchTranslation = mmt.handleCallback(body, signature, Metadata.class);
// --- Request ---
var opts = new TranslateOptions
{
    Metadata = new Dictionary<string, dynamic>
    {
        { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() }
    },
    IdempotencyKey = "b7f04ab3-68d6-47c0-8eea-0743a710b620"
};

const string webhook = "https://example.com";
var enqueued = mmt.BatchTranslate(webhook, "en", "it", "Hello world.", opts);

// --- Callback ---
// body must be an object or a json string
// signature must be the value of 'x-modernmt-signature' header
BatchTranslation batchTranslation = mmt.HandleCallback(body, signature);
// --- Request ---
$webhook = "https://example.com";
$enqueued = $mmt->batchTranslate($webhook, "en", "it", "Hello world.", null, null, [
    "metadata" => [
        "timestamp" => floor(microtime(true) * 1000)
    ],
    "idempotency_key" => "b7f04ab3-68d6-47c0-8eea-0743a710b620"
]);

// --- Callback ---
// body must be an associative array or a json string
// signature must be the value of 'x-modernmt-signature' header
$batchTranslation = $mmt->handleCallback($body, $signature);

RESPONSE

{
  "status": 200,
  "data": {
    "enqueued": true
  }
}

CALLBACK

{
  "result": {
    "status": 200,
    "data": {
      "translation": "Ciao mondo.",
      "billedCharacters": 12,
      "characters": 12,
    }
  },
  "metadata": {
    "timestamp": 1676023422231
  }
}

Allows to translate an input text or a list of texts asynchronously. The response will be delivered to the given webhook with retry methods up to 48h if it does not return a successful status code (2xx).

Request parameters

Name Description
webhook The endpoint where the response will be delivered, https is mandatory
metadata An object with custom metadata which will be returned in the response
source The language code (ISO 639-1) of the source text(s). If omitted, ModernMT will attempt to detect the source language automatically and return it within the response
target The language code (ISO 639-1) to use for translation of the input text(s)
q The input text or an array of texts to be translated. The text may include one or multiple sentences. Translations are returned in the same order as they are requested. If no source is provided, the array can include texts in different languages. The maximum length of the array is 128. See the note about tags handling
context_vector The context vector to use for the translation of the input text(s). This is necessary for adaptation
hints The hints for the context vector. If context_vector is omitted, it will be created automatically including those memories only
glossaries The glossaries to use for the translation of the input text(s)
ignore_glossary_case When handling glossaries for translation, ModernMT applies them in a case sensitive manner. This boolean parameter can alter this default behavior. True will apply the specified glossaries in a case-insensitive fashion, false will maintain case sensitivity in glossary application
multiline Given a long text, ModernMT automatically decides if to split the text in sub-sentences in order to provide a better translation result. This boolean parameter can force this behavior. True will always attempt to split, false disables it
format The input text format, see tags handling. Options currently available: text/plain, text/xml, text/html and application/xliff+xml. Default is auto-detected
alt_translations Include several alternative translations in the response. This parameter specifies the maximum number of alternative translations to be produced (the actual number can be equal or less than the specified value), the default is 0 (disabled) and the maximum value is 32. Please note that the usage of this parameter may impact response time
session The session identifier, see session
mask_profanities A boolean which indicates if ModernMT has to detect and mask profanities in translation. Default is false

Result

The batch API returns a JSON with the following structure:

Name Description
enqueued A boolean which indicates if the request has been added to the translation queue or has been ignored, see idempotency

Callback

The JSON which will be delivered to the given webhook has the following structure:

Name Description
result The result as if the call were made to the translate endpoint
metadata The metadata object given in the request, if present

Check signatures

The callback sent to your endpoint includes a signature in the x-modernmt-signature header. This allows you to verify that the data were sent by ModernMT, not by a third party.

Signature is a JWT token signed with RS256 algorithm, can be verified using any JWT library with ModernMT public key as secret.

Public key can be retrieved using the following GET endpoint: /translate/batch/key. Response contains the field publicKey which is encoded in base64. This is the recommended way of retrieving the public key, alternatively you can download it here: modernmt.key.pub

Idempotency

This endpoint supports idempotency for safely retrying requests without accidentally performing the same translation twice. This is useful when an API call is disrupted in transit and you do not receive a response, for example due to a network error. In this case you can retry with the same idempotency key to guarantee that no more than one translation request is created.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. We suggest using a random string with enough entropy to avoid collisions (eg. UUIDv4).

To perform an idempotent request, provide an additional x-idempotency-key: <key> header to the HTTP request. Subsequent retries of the same request will return a response including the x-idempotent-replayed: true header.

Any idempotency key will have effect for 2 days.

Context vector

The context vector is the object which leverages ModernMT adaptation during the translation. It consists of a list of memories, each one with a corresponding weight. The higher the weight is, the more the memory content will influence the translation result. The maximum weight which can be assigned to a memory is 1 and the decimal place accuracy is 3.

A context vector is represented by a string which contains a list of couples separated by a comma. Each couple contains the memory id and the corresponding weight separated by a colon. This is an example of a context vector: 37787:0.457,37784:0.2. It contains the memory 37787 with a weight of 0.457, and the memory 37784 with a weight of 0.2.

Hints

This parameter is a string which contains a list of memory ids separated by a comma. It can be used to force the assignment of the maximum weight to the given list of memories. If a non-existent memory is provided, it will be ignored.

Glossaries

This parameter is a string, consisting of a list of memory ids separated by a comma, that denotes the glossaries to be used during the translation. Therefore, when included, it indicates that the glossary entries contained in the specified memories are to be used. If a non-existent memory is provided, it will be ignored.

Context vector guessing from raw text

GET /context-vector - FILE

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    -F "content=@path/to/text_file" \
    -F "source=en" \
    -F "targets=it" \
    -F "targets=es" \
    "https://api.modernmt.com/context-vector"
const contextVectors = await mmt.getContextVectorFromFile("en", ["es", "it"], "path/to/file.txt") // or ReadStream
context_vectors = mmt.get_context_vector_from_file("en", ["es", "it"], "path/to/file.txt")  # or stream
contextVectors, err := mmt.GetContextVectorsFromFilePath("en", []string{"es", "it"}, "path/to/file.txt", nil, 0, "") // or *os.File
String contextVectors = mmt.getContextVectorFromFile("en", Arrays.asList("es", "it"), "path/to/file.txt"); // or File
var contextVectors = mmt.GetContextVectorFromFile("en", new List<string>{"es", "it"}, "path/to/file.txt"); // or FileStream
$context_vectors = $mmt->get_context_vector_from_file("en", ["es", "it"], "path/to/file.txt");

RESPONSE

{
  "status": 200,
  "data": {
    "source": "en",
    "vectors": {
      "it": "37787:0.191,37784:0.163,37790:0.14,37791:0.092"
    }
  }
}

GET /context-vector - TEXT

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    -F "text=This is an example text for context vector computation" \
    -F "source=en" \
    -F "targets=it" \
    -F "targets=es" \
    "https://api.modernmt.com/context-vector"
const contextVectors = await mmt.getContextVector("en", ["es", "it"], "This is an example text for context vector computation")
context_vectors = mmt.get_context_vector("en", ["es", "it"], "This is an example text for context vector computation")
contextVectors, err := mmt.GetContextVectors("en", []string{"es", "it"}, "This is an example text for context vector computation", nil, 0)
String contextVectors = mmt.getContextVector("en", Arrays.asList("es", "it"), "This is an example text for context vector computation");
var contextVectors = mmt.GetContextVector("en", new List<string>{"es", "it"}, "This is an example text for context vector computation");
$context_vectors = $mmt->get_context_vector("en", ["es", "it"], "This is an example text for context vector computation");

RESPONSE

{
  "status": 200,
  "data": {
    "source": "en",
    "vectors": {
      "it": "37790:0.167,37787:0.058,37784:0.054,37791:0.019"
    }
  }
}

ModernMT can analyze a given content, compare it with the memories content, and automatically create a context vector which can be used in the attempt to maximize the translation quality. This API returns the context vector which is the result of that automatic analysis for the provided content.

Request parameters

Name Description
source The language code (ISO 639-1) of the source content
targets The language codes (ISO 639-1) of the targets, separated by a comma. The response will contain a different vector for each target provided
content The text file to be analyzed
text The text to be analyzed. This parameter is required if content is omitted, ignored otherwise
hints The hints for the context vector
limit The maximum number of memories to include in the vector. Lowest weight memories will be filtered out. If omitted or zero, no limit will be applied.
compression Specifies the compression algorithm. Required if content is compressed. Supported algorithms: gzip

Result

Name Description
source The language code (ISO 639-1) of the source content provided in the request
vectors A JSON object whose keys are the target language codes provided in the request, each one with the corresponding context vector as value

Memories

ENDPOINTS

# Management
GET /memories
GET /memories/:id
POST /memories
PUT /memories/:id
DELETE /memories/:id

# Content
POST /memories/:id/content
PUT /memories/:id/content

# Glossary
POST /memories/:id/glossary
PUT /memories/:id/glossary

GET /import-jobs/:id

In ModernMT a memory is an entity that stores sentences and their corresponding translation. The memories are used in ModernMT through the context vector to perform real-time adaptation.

To obtain the best adaptation results, it’s recommended to create a separate translation memory for each domain (eg. memory A for legal stuff and memory B for medical stuff).

It is not necessary to split up memories content by language pairs instead. In the translation function ModernMT will automatically ignore content which does not match the translation’s language pairs, even for memories provided as hints.

A memory can also include glossary entries. In ModernMT, a glossary entry is used to specify a particular translation of a term, superseding the translation that would typically be generated by the MT system.

The JSON representation of a memory has the following structure:

Name Description
id The memory’s unique identifier (integer)
name The name of the memory. Symbols, numbers and spaces are allowed
description The description of the memory. Symbols, numbers and spaces are allowed
creationDate The memory creation date and time expressed according to ISO 8601

Management

Retrieve all memories

GET /memories

curl -H "MMT-ApiKey: YOUR_API_KEY" "https://api.modernmt.com/memories"
const memories = await mmt.memories.list()
memories = mmt.memories.list()
memories, err := mmt.Memories.List()
List<Memory> memories = mmt.memories.list();
var memories = mmt.Memories.List();
$memories = $mmt->memories->get_all();

RESPONSE

{
  "status": 200,
  "data": [
    {
      "id": 37784,
      "creationDate": "2021-03-19T09:46:59+00:00",
      "name": "legal"
    },
    ...
    {
      "id": 37791,
      "creationDate": "2021-03-19T09:47:21+00:00",
      "name": "medical"
    }
  ]
}

This endpoint allows to retrieve a list of your memories. The list is sorted by creation date, with the least recent memories appearing first.

Request parameters

None.

Result

Returns an array containing a JSON representation or your memories.

Retrieve memory metadata

GET /memories/:id

curl -H "MMT-ApiKey: YOUR_API_KEY" "https://api.modernmt.com/memories/37790"
const memory = await mmt.memories.get(37790)
memory = mmt.memories.get(37790)
memory, err := mmt.Memories.Get(37790)
Memory memory = mmt.memories.get(37790);
var memory = mmt.Memories.Get(37790);
$memory = $mmt->memories->get(37790);

RESPONSE

{
  "status": 200,
  "data": {
    "id": 37790,
    "creationDate": "2021-03-19T09:46:59+00:00",
    "name": "legal"
  }
}

This endpoint allows to retrieve the metadata of a memory. You need to specify the memory unique identifier (id).

Request parameters

None.

Result

Returns a JSON representation of the requested memory.

Create new memory

POST /memories

curl -X POST \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"name": "chemistry"}' \
    "https://api.modernmt.com/memories"
const memory = await mmt.memories.create("chemistry")
memory = mmt.memories.create("chemistry")
memory, err := mmt.Memories.Create("chemistry", "")
Memory memory = mmt.memories.create("chemistry");
var memory = mmt.Memories.Create("chemistry");
$memory = $mmt->memories->create("chemistry");

RESPONSE

{
  "status": 200,
  "data": {
    "id": 37790,
    "creationDate": "2021-04-12T15:24:26+00:00",
    "name": "chemistry"
  }
}

This endpoint allows to create a memory.

Request parameters

Name Description
name The name of the memory (different memories can share the same name)
description The description of the memory
external_id The memory key from MyMemory, prefixed with x_mm-. Its content will be automatically imported

Result

Returns a JSON representation of the created memory.

Update memory metadata

PUT /memories/:id

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"name": "physical chemistry"}' \
    "https://api.modernmt.com/memories/37790"
const memory = await mmt.memories.edit(37790, "physical chemistry")
memory = mmt.memories.edit(37790, "physical chemistry")
memory, err := mmt.Memories.Edit("physical chemistry", "")
Memory memory = mmt.memories.edit(37790, "physical chemistry");
var memory = mmt.Memories.Edit(37790, "physical chemistry");
$memory = $mmt->memories->edit(37790, "physical chemistry");

RESPONSE

{
  "status": 200,
  "data": {
    "id": 37790,
    "creationDate": "2021-04-12T15:24:26+00:00",
    "name": "physical chemistry"
  }
}

This endpoint allows to update the metadata of a memory. You need to specify the memory unique identifier (id). Any parameters not provided will be left unchanged, but at least one is required. Returns a JSON representation of the updated memory.

Request parameters

Name Description
name The name of the memory
description The description of the memory

Result

Returns a JSON representation of the updated memory.

Delete memory and its content

DELETE /memories/:id

curl -X DELETE \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    "https://api.modernmt.com/memories/37790"
const memory = await mmt.memories.delete(37790)
memory = mmt.memories.delete(37790)
memory, err := mmt.Memories.Delete(37790)
Memory memory = mmt.memories.delete(37790);
var memory = mmt.Memories.Delete(37790);
$memory = $mmt->memories->delete(37790);

RESPONSE

{
  "status": 200,
  "data": {
    "id": 37790,
    "creationDate": "2021-04-12T15:24:26+00:00",
    "name": "physical chemistry"
  }
}

This endpoint allows to permanently delete a memory and its content. It cannot be undone. You need to specify the memory unique identifier (id).

Request parameters

None.

Response

Returns a JSON representation of the deleted memory or a response with status code 404 if the memory is not found.

Content

Store memory content

POST /memories/:id/content - TMX FILE

curl -X POST \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    -F "tmx=@path/to/tmx_file" \
    "https://api.modernmt.com/memories/37790/content"
const importJob = await mmt.memories.import(37790, "path/to/file.tmx") // or ReadStream
import_job = mmt.memories.import_tmx(37790, "path/to/file.tmx")  # or stream
importJob, err := mmt.Memories.ImportTmxPath(37790, "path/to/file.tmx", "") // or *os.File
ImportJob importJob = mmt.memories.importTmx(37790, "path/to/file.tmx"); // or File
var importJob = mmt.Memories.Import(37790, "path/to/file.tmx"); // or FileStream
$import_job = $mmt->memories->import(37790, "path/to/file.tmx");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "00000000-0000-0000-0000-0000000379fc",
    "memory": 37790,
    "size": 18818,
    "progress": 0
  }
}

POST /memories/:id/content - SENTENCE-TRANSLATION PAIR

curl -X POST \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source":"en", "target":"it", "tuid":"1", "sentence":"This is a test.", "translation":"Questo è un test."}' \
    "https://api.modernmt.com/memories/37790/content"
const importJob = await mmt.memories.add(37790, "en", "it", "This is a test.", "Questo è un test.", "1")
import_job = mmt.memories.add(37790, "en", "it", "This is a test.", "Questo è un test.", "1")
importJob, err := mmt.Memories.Add(37790, "en", "it", "This is a test.", "Questo è un test.", "1")
ImportJob importJob = mmt.memories.add(37790, "en", "it", "This is a test.", "Questo è un test.", "1");
var importJob = mmt.Memories.Add(37790, "en", "it", "This is a test.", "Questo è un test.", "1");
$import_job = $mmt->memories->add(37790, "en", "it", "This is a test.", "Questo è un test.", "1");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "80000001-0000-0000-0000-0000049c6374",
    "memory": 37790,
    "size": 1,
    "progress": 0
  }
}

This section describes API functions to store sentences and their corresponding translation into memories. You need to specify the memory unique identifier (id). Multiple pairs can be stored at once using a tmx file, in that case the only required parameters are tmx and compression (if any). To store a single pair the other parameters are required.

Request parameters

Name Description
tmx The tmx file which content will be imported into the memory
compression Specifies the compression algorithm. Required if tmx is compressed. Supported algorithms: gzip
source The language code (ISO 639-1) of the source sentence. Ignored if tmx is provided, required otherwise
target The language code (ISO 639-1) of the translated sentence. Ignored if tmx is provided, required otherwise
sentence The source sentence. Ignored if tmx is provided, required otherwise
translation The translation of the source sentence. Ignored if tmx is provided, required otherwise
tuid A string identifier, necessary if you will need to update the given sentence-translation pair. Ignored if tmx is provided
session The session identifier, see session. Ignored if tmx is provided

Result

Returns the corresponding Import Job.

Update sentence-translation pair

PUT /memories/:id/content

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source":"en", "target":"it", "tuid":"1", "sentence":"This is a test.", "translation":"Questa è una prova."}' \
    "https://api.modernmt.com/memories/37790/content"
const importJob = await mmt.memories.replace(37790, "1", "en", "it", "This is a test.", "Questa è una prova.")
import_job = mmt.memories.replace(37790, "1", "en", "it", "This is a test.", "Questa è una prova.")
importJob, err := mmt.Memories.Replace(37790, "1", "en", "it", "This is a test.", "Questo è una prova.")
ImportJob importJob = mmt.memories.replace(37790, "1", "en", "it", "This is a test.", "Questa è una prova.");
var importJob = mmt.Memories.Add(37790, "1", "en", "it", "This is a test.", "Questa è una prova.");
$import_job = $mmt->memories->replace(37790, "1", "en", "it", "This is a test.", "Questa è una prova.");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "80000001-0000-0000-0000-0000049c7646",
    "memory": 37790,
    "size": 1,
    "progress": 0
  }
}

Update a sentence-translation pair in the given memory. You need to specify the memory unique identifier (id). None of the request parameters is optional.

Request parameters

Name Description
tuid The tuid of the sentence-translation pair to be updated
source The language code (ISO 639-1) of the source sentence to be updated
target The language code (ISO 639-1) of the translated sentence to be updated
sentence The updated source sentence
translation The updated translation
session The session identifier, see session

Result

Returns the corresponding Import Job.

Glossary

Store glossary content

POST /memories/:id/glossary - CSV FILE

curl -X POST \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    -F "csv=@path/to/file.csv" \
    -F 'type=unidirectional' \
    "https://api.modernmt.com/memories/37790/glossary"
const importJob = await mmt.memories.importGlossary(37790, "/path/to/file.csv", "unidirectional"); // or ReadStream
import_job = mmt.memories.import_glossary(37790, "/path/to/file.csv", "unidirectional")  # or stream
importJob, err := mmt.Memories.ImportGlossaryPath(37790, "path/to/file.csv", "unidirectional", "") // or *os.File
ImportJob importJob = mmt.memories.importGlossary(37790, "path/to/file.csv", "unidirectional"); // or File
var importJob = mmt.Memories.ImportGlossary(37790, "path/to/file.csv", "unidirectional"); // or FileStream
$importJob = $mmt->memories->importGlossary(37790, "path/to/file.csv", "unidirectional");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "00000000-0000-0000-0000-0000000379fc",
    "memory": 37790,
    "size": 18818,
    "progress": 0
  }
}

POST /memories/:id/glossary - TERMS

curl -X POST \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"tuid":"1", "type":"equivalent",
    "terms":[{"term": "test", "language": "en"}, {"term": "prova", "language": "it"}, {"term": "prueba", "language": "es"}]}' \
    "https://api.modernmt.com/memories/37790/glossary"
const terms = [
    {term: "test", language: "en"},
    {term: "prova", language: "it"},
    {term: "prueba", language: "es"}
];

const importJob = await mmt.memories.addToGlossary(37790, terms, "equivalent", "1");
terms = [
    {"term": "test", "language": "en"},
    {"term": "prova", "language": "it"},
    {"term": "prueba", "language": "es"},
]

import_job = mmt.memories.add_to_glossary(37790, terms, "equivalent", "1")
terms := []GlossaryTerm{{
    Term:     "test",
    Language: "en",
}, {
    Term:     "prova",
    Language: "it",
}, {
    Term:     "prueba",
    Language: "es",
}}

importJob, err := mmt.Memories.AddToGlossary(37790, terms, "equivalent", "1")
List<GlossaryTerm> terms = new ArrayList<>();
terms.add(new GlossaryTerm("test", "en"));
terms.add(new GlossaryTerm("prova", "it"));
terms.add(new GlossaryTerm("prueba", "es"));

ImportJob importJob = mmt.memories.addToGlossary(37790, terms, "equivalent", "1");
var terms = new List<GlossaryTerm>
{
    new("test", "en"),
    new("prova", "it"),
    new("prueba", "es"),
};

var importJob = mmt.Memories.AddToGlossary(37790, terms, "equivalent", "1");
$terms = [
    ["term" => "test", "language" => "en"],
    ["term" => "prova", "language" => "it"],
    ["term" => "prueba", "language" => "es"]
];

$importJob = $mmt->memories->addToGlossary(37790, $terms, "equivalent", "1");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "80000001-0000-0000-0000-0000049c6374",
    "memory": 37790,
    "size": 1,
    "progress": 0
  }
}

This section describes API functions to store glossary entries into memories. You need to specify the memory unique identifier (id). Multiple entries can be stored at once using a csv file, in that case the only required parameters are csv, type and compression (if any). To store a single set of entries the other parameters are required.

Request parameters

Name Description
csv The csv file which content will be imported into the memory
compression Specifies the compression algorithm. Required if csv is compressed. Supported algorithms: gzip
terms The glossary terms. Ignored if csv is provided, required otherwise
type A string indicating the glossary type. Can be defined as either unidirectional or equivalent. Always required
tuid A string identifier, used to update the given glossary entry. Ignored if tmx is provided, forbidden if type is unidirectional, required if type is equivalent

Result

Returns the corresponding Import Job.

Update glossary entry

PUT /memories/:id/glossary

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"tuid":"1", "type":"equivalent",
    "terms":[{"term": "test", "language": "en"}, {"term": "prova", "language": "it"}, {"term": "prueba", "language": "es"}]}' \
    "https://api.modernmt.com/memories/37790/glossary"
const terms = [
    {term: "test", language: "en"},
    {term: "prova", language: "it"},
    {term: "prueba", language: "es"}
];

const importJob = await mmt.memories.replaceInGlossary(37790, terms, "equivalent", "1");
terms = [
    {"term": "test", "language": "en"},
    {"term": "prova", "language": "it"},
    {"term": "prueba", "language": "es"},
]

import_job = mmt.memories.replace_in_glossary(37790, terms, "equivalent", "1")
terms := []GlossaryTerm{{
    Term:     "test",
    Language: "en",
}, {
    Term:     "prova",
    Language: "it",
}, {
    Term:     "prueba",
    Language: "es",
}}

importJob, err := mmt.Memories.ReplaceInGlossary(37790, terms, "equivalent", "1")
List<GlossaryTerm> terms = new ArrayList<>();
terms.add(new GlossaryTerm("test", "en"));
terms.add(new GlossaryTerm("prova", "it"));
terms.add(new GlossaryTerm("prueba", "es"));

ImportJob importJob = mmt.memories.replaceInGlossary(37790, terms, "equivalent", "1");
var terms = new List<GlossaryTerm>
{
    new("test", "en"),
    new("prova", "it"),
    new("prueba", "es"),
};

var importJob = mmt.Memories.ReplaceInGlossary(37790, terms, "equivalent", "1");
$terms = [
    ["term" => "test", "language" => "en"],
    ["term" => "prova", "language" => "it"],
    ["term" => "prueba", "language" => "es"]
];

$importJob = $mmt->memories->replaceInGlossary(37790, $terms, "equivalent", "1");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "80000001-0000-0000-0000-0000049c7646",
    "memory": 37790,
    "size": 1,
    "progress": 0
  }
}

Update terms of a glossary entry in the given memory. You need to specify the memory unique identifier (id).

Request parameters

Name Description
terms The glossary terms to be updated
type The string identifying the glossary type (either unidirectional or equivalent)
tuid The tuid of the glossary entry to be updated. forbidden if type is unidirectional, required if type is equivalent

Result

Returns the corresponding Import Job.

Terms Structure

EXAMPLE

[
    {
        "term": "test",
        "language": "en"
    },
    {
        "term": "prova",
        "language": "it"
    },
    {
        "term": "prueba",
        "language": "es"
    }
]

The terms parameter consists of a list of terms from a glossary entry in multiple languages.

Every item in this list is an object that contains the string value of the term and its corresponding language code (ISO 639-1).

Duplicated languages are not permitted.

When type is unidirectional, exactly two terms are expected.

When type is equivalent, at least two terms are expected.

Import job

An Import Job is an object which represents the import operation of content in a memory. Each import operation function returns the corresponding Import Job.

The JSON representation of an Import Job has the following structure:

Name Description
id The id of the import job (uuid)
memory The id of the corresponding memory
size The number of sentence-translation pairs of the import job
progress Indicates the percentage of progress of the import job. The value can be between 0 and 1. A value of 1 indicates that the job is completed

Retrieve TMX import status

GET /import-jobs/:id - IMPORT JOB

curl -H "MMT-ApiKey: YOUR_API_KEY" \
    "https://api.modernmt.com/import-jobs/00000000-0000-0000-0000-0000000379fc"
const importJob = await mmt.memories.getImportStatus("00000000-0000-0000-0000-0000000379fc")
import_job = mmt.memories.get_import_status("00000000-0000-0000-0000-0000000379fc")
importJob, err := mmt.Memories.GetImportStatus("00000000-0000-0000-0000-0000000379fc")
ImportJob importJob = mmt.memories.GetImportStatus("00000000-0000-0000-0000-0000000379fc");
var importJob = mmt.Memories.GetImportStatus("00000000-0000-0000-0000-0000000379fc");
$import_job = $mmt->memories->get_import_status("00000000-0000-0000-0000-0000000379fc");

RESPONSE

{
  "status": 200,
  "data": {
    "id": "00000000-0000-0000-0000-0000000379fc",
    "memory": 37790,
    "size": 18818,
    "progress": 1
  }
}

Returns the JSON representation of an Import Job. You need to specify the memory unique identifier (uuid).

Request parameters

None.

Result

Returns the corresponding Import Job.

Quality Estimation

Allows to evaluate the quality of a translation or a list of translations.

GET /qe - SINGLE TEXT

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source":"en", "target":"it",
    "sentence":"Hello world", "translation": "Ciao mondo"}' \
    "https://api.modernmt.com/qe"
const qe = await mmt.qe("en", "it", "This is an example", "Questo è un esempio")
score = mmt.qe("en", "it", "Hello world", "Ciao mondo")
qe, err := mmt.Qe("en", "it", "Hello world", "Ciao mondo")
QualityEstimation qe = mmt.qe("en", "it", "Hello world", "Ciao mondo");
var score = mmt.Qe("en", "it", "Hello world", "Ciao mondo");
$qe = $mmt->qe("en", "it", "Hello world", "Ciao mondo");

RESPONSE

{
  "status": 200,
  "data": {
    "score": 0.854
  }
}

GET /qe - MULTIPLE TEXTS

curl -X POST \
    -H "X-HTTP-Method-Override: GET" \
    -H "Content-Type: application/json" \
    -H "MMT-ApiKey: YOUR_API_KEY" \
    --data '{"source": "en", "target":"it",
    "sentence":["Hello world", "This is an example"],
    "translation":["Ciao mondo", "Questo è un esempio"]}' \
    "https://api.modernmt.com/qe"
const qes = await mmt.qe("en", "it",
    ["Hello world", "This is an example"], ["Ciao mondo", "Questo è un esempio"])
scores = mmt.qe("en", "it", ["Hello world", "This is an example"],
                ["Ciao mondo", "Questo è un esempio"])
qes, err := mmt.QeList("en", "it",
    []string{"Hello world", "This is an example"},
    []string{"Ciao mondo", "Questo è un esempio"})
List<QualityEstimation> qes = mmt.qe("en", "it",
        Arrays.asList("Hello world", "This is an example"),
        Arrays.asList("Ciao mondo", "Questo è un esempio"));
var scores = mmt.Qe("en", "it",
    new List<string>{"Hello world", "This is an example"},
    new List<string>{"Ciao mondo", "Questo è un esempio"});
$qes = $mmt->qe("en", "it",
    ["Hello world", "This is an example"], ["Ciao mondo", "Questo è un esempio"]);

RESPONSE

{
  "status": 200,
  "data": [
    {
      "score": 0.902
    },
    {
      "score": 0.956
    }
  ]
}

Request parameters

Name Description
source The language code (ISO 639-1) of the source sentence(s)
target The language code (ISO 639-1) of the translation(s)
sentence The input sentence or an array of sentences. The total number of characters must be less than or equal to 10240, the maximum length of the array is 128
translation The input translation or an array of translations. The total number of characters must be less than or equal to 10240, the maximum length of the array is 128

Result

The quality estimation API returns a JSON (or an array of JSONs if multiple sentences were provided, in the given order) with the following structure:

Name Description
score Represents the quality of the translation. The value can be between 0 (lower) and 1 (higher)