Introduction
https://api.modernmt.com/
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:
MMT-Platform
: the name of the client.MMT-PlatformVersion
: the version of the client.
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:
- Product names: For instance, "Translated" should remain "Translated" across all languages.
- Ambiguous terms: Words like "crane" can refer to a type of machinery or a bird species. If you're translating a text about construction, using a glossary can ensure that ModernMT uses the machinery-related translation of "crane", not the bird definition.
- Borrowed words: There are instances where the MT engine might not translate foreign words that have been historically integrated into another language, such as the French term "côte de boeuf". However, using a glossary allows you to bypass this and ensure that these words are translated appropriately, for example, to "beef rib" in English.
- Abbreviations: Terms that are commonly shortened in a particular industry or area of interest can be clarified with a glossary. For example, "TM" can be specified to mean "Translation Memory".
However, it's also important to note which terms are less suitable for MT glossaries, including:
- Verbs: Currently, MT glossaries might struggle with consistently adapting verbs in terms of grammatical person, number, gender, tense, aspect, mood, voice, formality, clusivity, transitivity, or valency. Therefore, we recommend not using verbs as glossary terms.
- Inflected languages: Languages that contain a high number of cases and grammatical genders present a challenge for MT glossaries. At present, they aren't very proficient at adjusting the form or terminations of these words depending on their usage or position in sentences.
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
{
"status": 200,
"data": ...
}
{
"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 Pashto - 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();
{
"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");
{
"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"]);
{
"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.");
{
"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"]);
{
"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]);
{
"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],
]);
{
"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
]);
{
"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
]);
{
"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:
- Tags are identified and extracted from the text.
- Pure text is de-escaped, entities are replaced with the actual literal:
<
is replaced with<
.
Post-processing:
- Text is escaped following the text format conventions:
<
is replaced with<
. - Tags are positioned in the translation based on the alignments.
Example:
- input:
You'll see the <span id="example-span">example</span>
- pre-processed:
You'll see the example
- translated:
Vedrai l'esempio
- post-processed:
Vedrai l'<span id="example-span">esempio</span>
Do-not-translate BETA
This feature allows to designate parts of the input text that do not have to be translated. Ideal for preserving proper nouns, technical terms, and branded content. These segments retain their original meaning and are seamlessly integrated into the surrounding translated content.
To use the do-not-translate feature, wrap the content to be excluded from translation in any XML/HTML tag containing one of the following attributes:
- translate="no":
<p>The Leaning Tower of Pisa is known as <span translate="no">Torre pendente di Pisa</span> in Italian.</p>
- class="notranslate":
<p>The Leaning Tower of Pisa is known as <span class="notranslate">Torre pendente di Pisa</span> in Italian.</p>
Batch
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);
{
"status": 200,
"data": {
"enqueued": true
}
}
{
"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.
Quality Estimation
Allows to evaluate the quality of a translation or a list of translations.
GET /translate/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/translate/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");
{
"status": 200,
"data": {
"score": 0.854
}
}
GET /translate/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/translate/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"]);
{
"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) |
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");
{
"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");
{
"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
# 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();
{
"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);
{
"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");
{
"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");
{
"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);
{
"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");
{
"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");
{
"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.");
{
"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");
{
"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");
{
"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");
{
"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
[
{
"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");
{
"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.