Translation API v2 with Quality Estimation (QE)

Endpoint: POST <https://console.custom.mt/translation/text_translate_v2>
Format: JSON over HTTPS
Version: Current (QE-enabled)

1. Overview

This endpoint performs segment-based machine translation using a predefined translation template and returns:

translated text segments;
Quality Estimation (QE) results for each segment.

The API supports batch translation and is designed for integration with:

CAT and TMS systems,
MT automation pipelines,
downstream workflows (auto-confirmation, segment locking, quality gating).

2. Key Concepts

Segment

A single element of the text[] array.
Each segment is translated and evaluated independently.

Batch Translation

The API accepts a batch of segments in a single request.

A single request may contain multiple segments in the text[] array.
Recommended batch size: up to 25 segments per request.
Larger batches may increase latency and are not recommended for real-time workflows.

Translation Template

A configuration entity that defines:

translation provider;
language pair;
fallback logic;
Quality Estimation settings and thresholds.

Quality Estimation (QE)

An automated process that evaluates translation quality without a reference translation.

Important characteristics:

QE is performed per segment.
Each segment receives its own score and decision flags.
QE results do not affect other segments in the same batch.

3. Request

HTTP Method

POST

Headers

Accept: application/json
Content-Type: application/json
token: <API_TOKEN>
X-CSRFToken: <CSRF_TOKEN>

Request Body

Field name	Type	Required	Description

Field name	Type	Required	Description
`text`	string[]	Yes	List of source text segments to be translated. Each array element is processed as an independent segment.
`template_name`	string	Yes	Name of the translation template defining provider, language pair, and QE configuration.
`error_empty_result`	boolean	No	Controls behavior if the translation result is empty.

Batch Processing Notes

Multiple segments can be submitted in a single request.
Recommended maximum batch size: 25 segments.
Segments are translated and evaluated independently.

Example Request

{
  "text": [
    "Текст для проверки работы опции QE",
    "Еще один сегмент для перевода"
  ],
  "template_name": "QE test template",
  "error_empty_result": false
}

4. Response

Top-level Response Fields

Field name	Type	Description

Field name	Type	Description
`translated_text`	string[]	Translated segments aligned by index with the input `text[]`.
`provider_index`	integer	Index of the selected provider configuration in the template.
`balancer`	integer	Load balancer identifier used for this request.
`provider`	string	Translation provider that performed the translation.
`qe`	object	Quality Estimation results per segment.
`usage`	object	Overall usage statistics for the request.

5. Quality Estimation (`qe`) Object

qe Fields

Field name	Type	Description

Field name	Type	Description
`messages`	array	List of QE-evaluated segments. Each entry corresponds to one source/target pair.
`usage`	object	Aggregated QE model usage statistics, grouped by model identifier.

Important Notes

QE is applied per segment, not per request.
Each segment receives an independent QE score and decision flags.

6. qe.messages[] Structure

Each element represents one translated segment and its QE evaluation.

Field name	Type	Description

Field name	Type	Description
`score`	object	Quality Estimation results produced by the QE model for this segment.
`message`	object	Source and translated text metadata for this segment.

7. message Object

Field name	Type	Description

Field name	Type	Description
`source`	string	Original source text of the segment.
`target`	string	Translated text of the segment.
`source_language`	string	Source language code (ISO-like).
`target_language`	string	Target language code (ISO-like).

8. QE Score Object (`score.open_ai`)

This object contains the Quality Estimation result produced by an OpenAI-based QE model.

Field name	Type	Description

Field name	Type	Description
`score`	number	Normalized QE score for the segment (range 0–1).
`usage`	object	LLM token usage for this segment evaluation.
`prompt_error`	string \| null	Error related to QE prompt construction, if any.
`error`	string \| null	Runtime or evaluation error, if any.
`is_success`	boolean	Indicates whether QE evaluation for this segment succeeded.
`lock_segment`	boolean	QE recommendation to lock this segment from editing.
`confirm_segment`	boolean	QE recommendation to automatically confirm this segment.
`success_score_value`	number	QE score threshold used to determine confirmation.

Semantic Notes

All QE fields apply only to the corresponding segment.
confirm_segment and lock_segment are automatic QE decisions, not human actions.
These flags are intended for CAT/TMS automation (auto-confirm, auto-lock).

9. QE Usage Object (`qe.usage`)

qe.usage is a map keyed by QE model identifier.

"usage": {
  "gpt-4o-2024-11-20": {
    "prompt_tokens": 89,
    "completion_tokens": 1
  }
}

Field name	Type	Description

Field name	Type	Description
`prompt_tokens`	integer	Number of input tokens consumed by the QE model.
`completion_tokens`	integer	Number of output tokens generated by the QE model.

10. Usage Object (Top-level)

Field name	Type	Description

Field name	Type	Description
`symbols_count`	integer	Total number of characters processed in the request.
`in_tokens_count`	integer	Input token count for translation (if applicable).
`out_tokens_count`	integer	Output token count for translation (if applicable).

11. Example Response

{
  "translated_text": [
    "Text for checking the operation of the QE option",
    "Another segment to translate"
  ],
  "provider_index": 0,
  "balancer": 3,
  "provider": "Google",
  "qe": {
    "messages": [
      {
        "score": {
          "open_ai": {
            "score": 0.85,
            "usage": {
              "prompt_tokens": 89,
              "completion_tokens": 1
            },
            "prompt_error": null,
            "error": null,
            "is_success": true,
            "lock_segment": false,
            "confirm_segment": true,
            "success_score_value": 0.7
          }
        },
        "message": {
          "source": "Текст для проверки работы опции QE",
          "target": "Text for checking the operation of the QE option",
          "source_language": "ru",
          "target_language": "en"
        }
      },
      {
        "score": {
          "open_ai": {
            "score": 0.85,
            "usage": {
              "prompt_tokens": 83,
              "completion_tokens": 1
            },
            "prompt_error": null,
            "error": null,
            "is_success": true,
            "lock_segment": false,
            "confirm_segment": true,
            "success_score_value": 0.7
          }
        },
        "message": {
          "source": "Еще один сегмент для перевода",
          "target": "Another segment to translate",
          "source_language": "ru",
          "target_language": "en"
        }
      }
    ],
    "usage": {
      "gpt-4o-2024-11-20": {
        "prompt_tokens": 172,
        "completion_tokens": 2
      }
    }
  },
  "usage": {
    "symbols_count": 63,
    "in_tokens_count": 0,
    "out_tokens_count": 0
  }
}

12. Mapping Quality Estimation → XLIFF 1.2

This section describes how QE results returned by the API can be mapped to XLIFF 1.2 standard attributes.

General Principles

Mapping is performed per segment.
QE decisions are applied without modifying segment content.
Standard XLIFF 1.2 attributes are used.

12.1 Mapping `confirm_segment → approved`

QE Field	Value	XLIFF 1.2 Attribute	Value

QE Field	Value	XLIFF 1.2 Attribute	Value
`confirm_segment`	`true`	`approved`	`"yes"`
`confirm_segment`	`false`	`approved`	`"no"` or omitted

Example:

<trans-unit id="1" approved="yes">
  <source>Текст для проверки работы опции QE</source>
  <target>Text for checking the operation of the QE option</target>
</trans-unit>

12.2 Mapping `lock_segment → translate`

QE Field	Value	XLIFF 1.2 Attribute	Value

QE Field	Value	XLIFF 1.2 Attribute	Value
`lock_segment`	`true`	`translate`	`"no"`
`lock_segment`	`false`	`translate`	`"yes"` or omitted