# MachineTranslation.com API Documentation

### Overview

The MachineTranslation.com API provides a streamlined and efficient way to translate content between different languages.

It supports:

* **Plain text translation** via JSON requests
* **Structured JSON file translation**, where keys and structure are preserved, and only string values are translated

The API supports multiple translation engines, ensuring reliable and high-quality translations for various language pairs.

### Base URLs

Text translation:

```
https://api.machinetranslation.com/pv1/translate
```

JSON file translation:

```
https://api.machinetranslation.com/pv1/translate/file
```

### Authentication

The API uses BEARER for authentication. Include your API key in the `Authorization` header for each request.

#### Example

```bash
Authorization: BEARER <your_api_key>
```

### Request an API Key

To access the MachineTranslation.com API, you need an API key. [Contact us](https://developer.machinetranslation.com/) to request for an API key.

### Endpoints

#### 1️⃣ Create Translation (Text)

Translate plain text from one language to another.

**HTTP Request**

**POST**

```
https://api.machinetranslation.com/pv1/translate
```

**Headers**

```
Authorization: BEARER <your_api_key>
Content-Type: application/json
```

**Request Body**

```json
{
  "text": "The text you want to translate",
  "source_language_code": "en",
  "target_language_code": "fr"
}
```

| Field                  | Type   | Required | Description                      |
| ---------------------- | ------ | -------- | -------------------------------- |
| text                   | string | Yes      | Text to be translated            |
| source\_language\_code | string | Yes      | Source language code (e.g. `en`) |
| target\_language\_code | string | Yes      | Target language code (e.g. `fr`) |

**Example Request**

```bash
curl --location 'https://api.machinetranslation.com/pv1/translate' \
--header 'Authorization: BEARER <your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "text": "MachineTranslation.com translates, compares, and recommends the best translations.",
  "source_language_code": "en",
  "target_language_code": "fr"
}'
```

**Response Example**

```json
{
  "translations": [
    {
      "engine": "google",
      "share_id": "cf733e14-ea86-4f6b-92fc-de9813197601",
      "source_text": "MachineTranslation.com translates, compares, and recommends the best translations.",
      "target_text": "MachineTranslation.com traduit, compare et recommande les meilleures traductions.",
      "source_word_count": 8,
      "target_word_count": 8,
      "source_language_code": "en",
      "target_language_code": "fr"
    }
  ],
  "meta": {
    "short_url": "https://machinetranslation.com/translations/cf733e14-ea86-4f6b-92fc-de9813197601",
    "total_words": 8
  }
}
```

**Response Fields**

* `translations`: Array of translation results from different engines
* `engine`: Translation engine used
* `share_id`: Unique ID for the translation
* `source_text`: Original text
* `target_text`: Translated text
* `source_word_count`: Word count of source text
* `target_word_count`: Word count of translated text
* `source_language_code`: Source language code
* `target_language_code`: Target language code
* `meta.short_url`: Shareable URL
* `meta.total_words`: Total word count

***

#### 2️⃣ Translate JSON File

Translate a `.json` file while preserving its original structure.

* JSON **keys and structure are preserved**
* **Only string values are translated**
* Numbers, booleans, arrays, and objects remain unchanged

**HTTP Request**

**POST**

```
https://api.machinetranslation.com/pv1/translate/file
```

**Headers**

```
Authorization: BEARER <your_api_key>
Content-Type: multipart/form-data
```

> Note: Most HTTP clients automatically handle multipart boundaries.

**Request Body (form-data)**

| Field                  | Type   | Required | Description                      |
| ---------------------- | ------ | -------- | -------------------------------- |
| file                   | file   | Yes      | JSON file to translate           |
| source\_language\_code | string | Yes      | Source language code (e.g. `en`) |
| target\_language\_code | string | Yes      | Target language code (e.g. `fr`) |

**Example Request**

```bash
curl --location 'https://api.machinetranslation.com/pv1/translate/file' \
--header 'Authorization: BEARER <your_api_key>' \
--form 'file=@"/path/to/file.json"' \
--form 'source_language_code="en"' \
--form 'target_language_code="fr"'
```

**Response Example**

```json
{
  "translated_json": {
    "title": "Texte traduit",
    "description": "La structure JSON originale est conservée"
  },
  "source_language_code": "en",
  "target_language_code": "fr"
}
```

**Notes**

* The response returns a `translated_json` object with the **same structure** as the uploaded file.

### Supported Languages

Below are the supported languages and their codes:

| Language Name            | Code     |
| ------------------------ | -------- |
| Acehnese                 | ace      |
| Afrikaans                | af       |
| Albanian                 | sq       |
| Amharic                  | am       |
| Arabic                   | ar       |
| Armenian                 | hy       |
| Assamese                 | as       |
| Asturian                 | ast      |
| Awadhi                   | awa      |
| Ayacucho Quechua         | quy      |
| Aymara                   | ay       |
| Aymara, Central          | ayr      |
| Azerbaijani              | az       |
| Azerbaijani, Northern    | azj      |
| Azerbaijani, Southern    | azb      |
| Balinese                 | ban      |
| Bambara                  | bm       |
| Banjar                   | bjn      |
| Bashkir                  | ba       |
| Basque                   | eu       |
| Belarusian               | be       |
| Bemba                    | bem      |
| Bengali                  | bn       |
| Bhojpuri                 | bho      |
| Bodo                     | brx      |
| Bosnian                  | bs       |
| Buginese                 | bug      |
| Bulgarian                | bg       |
| Cantonese (Traditional)  | yue      |
| Catalan                  | ca       |
| Cebuano                  | ceb      |
| Chhattisgarhi            | hne      |
| Chinese (Literary)       | lzh      |
| Chinese (Simplified)     | zh       |
| Chinese (Traditional)    | zh-TW    |
| Chokwe                   | cjk      |
| Corsican                 | co       |
| Crimean Tatar            | crh      |
| Croatian                 | hr       |
| Czech                    | cs       |
| Danish                   | da       |
| Dari                     | fa-AF    |
| Dhivehi / Divehi         | dv       |
| Dimli                    | diq      |
| Dinka (Southwestern)     | dik      |
| Dogri                    | doi      |
| Dutch                    | nl       |
| Dyula                    | dyu      |
| Dzongkha                 | dz       |
| English                  | en       |
| Esperanto                | eo       |
| Estonian                 | et       |
| Ewe                      | ee       |
| Faroese                  | fo       |
| Fijian                   | fj       |
| Filipino, Tagalog        | tl       |
| Finnish                  | fi       |
| Fon                      | fon      |
| French                   | fr       |
| French (Canada)          | fr-CA    |
| Frisian                  | fy       |
| Friulian                 | fur      |
| Galician                 | gl       |
| Ganda                    | lg       |
| Georgian                 | ka       |
| German                   | de       |
| Greek                    | el       |
| Gujarati                 | gu       |
| Haitian Creole           | ht       |
| Halh Mongolian           | khk      |
| Hausa                    | ha       |
| Hawaiian                 | haw      |
| Hebrew                   | he       |
| Hindi                    | hi       |
| Hmong                    | hmn      |
| Hmong Daw                | mww      |
| Hungarian                | hu       |
| Icelandic                | is       |
| Igbo                     | ig       |
| Ilocano / Iloko          | ilo      |
| Indonesian               | id       |
| Inuinnaqtun              | iu       |
| Inuktitut                | ikt      |
| Inuktitut (Latin)        | iu-Latn  |
| Irish                    | ga       |
| Italian                  | it       |
| Japanese                 | ja       |
| Javanese                 | jv       |
| Jingpho                  | kac      |
| Kabiyè                   | kbp      |
| Kabuverdianu             | kea      |
| Kabyle                   | kab      |
| Kamba                    | kam      |
| Kannada                  | kn       |
| Kanuri, Central          | knc      |
| Kashmiri (Arabic)        | kas      |
| Kashmiri (Devanagari)    | ks       |
| Kazakh                   | kk       |
| Khmer                    | km       |
| Kikuyu                   | ki       |
| Kimbundu                 | kmb      |
| Kinyarwanda              | rw       |
| Kongo                    | kg       |
| Konkani                  | gom      |
| Korean                   | ko       |
| Krio                     | kri      |
| Kurdish                  | ku       |
| Kurdish (Kurmanji)       | kmr      |
| Kurdish (Sorani)         | ckb      |
| Kyrgyz                   | ky       |
| Lao                      | lo       |
| Latgalian                | ltg      |
| Latin                    | la       |
| Latvian                  | lv       |
| Ligurian                 | lij      |
| Limburgish               | li       |
| Lingala                  | ln       |
| Lithuanian               | lt       |
| Lombard                  | lmo      |
| Lower Sorbian            | dsb      |
| Luba-Kasai               | lua      |
| Luxembourgish            | lb       |
| Macedonian               | mk       |
| Magahi                   | mag      |
| Maithili                 | mai      |
| Malagasy                 | mg       |
| Malay                    | ms       |
| Malayalam                | ml       |
| Maltese                  | mt       |
| Manipuri                 | mni      |
| Maori                    | mi       |
| Marathi                  | mr       |
| Meiteilon (Manipuri)     | mni-Mtei |
| Minangkabau              | min      |
| Mizo                     | lus      |
| Mongolian                | mn       |
| Mongolian (Cyrillic)     | mn-Cyrl  |
| Mongolian (Traditional)  | mn-Mong  |
| Mossi                    | mos      |
| Myanmar (Burmese)        | my       |
| Nepali                   | ne       |
| Nigerian Fulfulde        | fuv      |
| Norwegian (Bokmål)       | no       |
| Norwegian (Nynorsk)      | nn       |
| Nuer                     | nus      |
| Nyanja (Chichewa)        | ny       |
| Occitan                  | oc       |
| Odia (Oriya)             | or       |
| Oromo                    | om       |
| Oromo (West Central)     | gaz      |
| Pangasinan               | pag      |
| Papiamento               | pap      |
| Pashto                   | ps       |
| Persian (Farsi)          | fa       |
| Polish                   | pl       |
| Pashto (Southern)        | pbt      |
| Plateau Malagasy         | plt      |
| Portuguese (Brazil)      | pt       |
| Portuguese (Portugal)    | pt-PT    |
| Punjabi                  | pa       |
| Quechua                  | qu       |
| Queretaro Otomi          | otq      |
| Romanian                 | ro       |
| Rundi                    | rn       |
| Russian                  | ru       |
| Shona                    | sn       |
| Samoan                   | sm       |
| Sango                    | sg       |
| Sanskrit                 | sa       |
| Santali                  | sat      |
| Sardinian                | sc       |
| Scots Gaelic             | gd       |
| Sepedi                   | nso      |
| Serbian (Cyrillic)       | sr-Cyrl  |
| Serbian (Latin)          | sr-Latn  |
| Sesotho                  | st       |
| Sesotho sa Leboa         | nso      |
| Shan                     | shn      |
| Sicilian                 | scn      |
| Silesian                 | szl      |
| Sindhi                   | sd       |
| Sinhala (Sinhalese)      | si       |
| Slovak                   | sk       |
| Slovenian                | sl       |
| Somali                   | so       |
| Somali (Arabic)          | so       |
| Sotho (Northern)         | nso      |
| Sotho (Southern)         | st       |
| Spanish                  | es       |
| Spanish (Latin America)  | es-419   |
| Spanish (Mexico)         | es-MX    |
| Standard Latvian         | lvs      |
| Standard Malay           | zsm      |
| Sundanese                | su       |
| Swahili                  | sw       |
| Swati                    | ss       |
| Swedish                  | sv       |
| Tahitian                 | ty       |
| Tajik                    | tg       |
| Tamasheq                 | taq      |
| Tamazight, Central Atlas | tzm      |
| Tamil                    | ta       |
| Tatar (Latin)            | tt       |
| Tatar / Tartar           | tt       |
| Telugu                   | te       |
| Thai                     | th       |
| Tibetan                  | bo       |
| Tigrinya                 | ti       |
| Tok Pisin                | tpi      |
| Tongan                   | to       |
| Tosk Albanian            | als      |
| Tsonga                   | ts       |
| Tswana / Setswana        | tn       |
| Tumbuka                  | tum      |
| Turkish                  | tr       |
| Turkmen                  | tk       |
| Twi                      | tw       |
| Twi (Akan)               | ak       |
| Ukrainian                | uk       |
| Umbundu                  | umb      |
| Upper Sorbian            | hsb      |
| Urdu                     | ur       |
| Uyghur                   | ug       |
| Uzbek (Latin)            | uz       |
| Uzbek (Northern)         | uzn      |
| Venetian                 | vec      |
| Vietnamese               | vi       |
| Waray (Philippines)      | war      |
| Welsh                    | cy       |
| Wolof                    | wo       |
| Xhosa                    | xh       |
| Yiddish                  | yi       |
| Yiddish (Eastern)        | ydd      |
| Yoruba                   | yo       |
| Yucatec Maya             | yua      |
| Zulu                     | zu       |

### AI Translation Models & Smart AI Translation

MachineTranslation.com aggregates translations from multiple AI translation sources.

Rather than relying on a single model or provider, the platform compares outputs across top AI sources and applies SMART AI Translation to return the most reliable result by default.

**Currently Supported Translation Sources**

MachineTranslation.com currently supports AI and machine translation sources including, but not limited to:

* AI21
* Amazon Translate
* Amazon Nova
* ChatGPT
* Anthopic Claude
* DeepL
* DeepSeek
* Facebook (Meta)
* Gemini
* GLM (Z.ai)
* Google Translate
* Grok (xAI)
* Kimi (MoonshotAI)
* LibreTranslate
* Lingvanex
* LLaMA (Meta)
* Microsoft Translator
* Mistral AI
* ModernMT
* Niutrans
* Qwen
* Royalflush


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tomedes.gitbook.io/machinetranslation.com-api/machinetranslation.com-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.