From 7f11beb59e9cae5ca781cab275f10be5069e61b1 Mon Sep 17 00:00:00 2001 From: Timothy Curek Date: Tue, 22 Sep 2026 11:54:00 +0200 Subject: [PATCH 1/3] docs: rework Quality Evaluation as a document-translation beta Reports are now requested with enable_quality_evaluation on POST /v2/document and polled at GET /v1/quality-evaluations/{job_id}. Drops the standalone submit endpoint and the summary object, adds segment text and glossary entries, and folds the deleted overview page into the poll reference. --- api-reference/openapi.json | 354 ++++++------------ api-reference/openapi.yaml | 270 +++++-------- api-reference/quality-evaluation.mdx | 35 -- api-reference/quality-evaluation/poll.mdx | 115 ++++-- api-reference/quality-evaluation/submit.mdx | 20 - docs.json | 16 + docs/best-practices/document-translations.mdx | 70 +++- docs/resources/roadmap-and-release-notes.mdx | 6 + standards/ia.yaml | 2 +- 9 files changed, 379 insertions(+), 509 deletions(-) delete mode 100644 api-reference/quality-evaluation.mdx delete mode 100644 api-reference/quality-evaluation/submit.mdx diff --git a/api-reference/openapi.json b/api-reference/openapi.json index e186ba34..eea9b13f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -79,7 +79,7 @@ }, { "name": "QualityEvaluation", - "description": "**Closed alpha.** Evaluate translation quality. Submit source/target segment pairs and retrieve per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs." + "description": "**Beta.** Retrieve a quality evaluation report for a document DeepL has translated. Reports are requested with `enable_quality_evaluation` on `POST /v2/document` and polled here. A report lists per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs." } ], "x-hideTryItPanel": true, @@ -1145,6 +1145,15 @@ "translation_memory_id": "[yourTranslationMemoryId]", "translation_memory_threshold": 75 } + }, + "QualityEvaluation": { + "summary": "Requesting a quality evaluation report (beta)", + "value": { + "source_lang": "EN", + "target_lang": "DE", + "file": "@document.docx", + "enable_quality_evaluation": true + } } }, "schema": { @@ -1206,6 +1215,11 @@ "type": "boolean", "default": false }, + "enable_quality_evaluation": { + "description": "(beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) with it for a per-segment report of translation issues. The translation itself is unaffected.\n\n**Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) only.\n\nRejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`.", + "type": "boolean", + "default": false + }, "enable_beta_languages": { "description": "This parameter is maintained for backward compatibility and has no effect.", "type": "boolean", @@ -1239,6 +1253,11 @@ "description": "A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document.", "type": "string", "example": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + }, + "quality_evaluation_job_id": { + "description": "(beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll).", + "type": "string", + "example": "04DE5AD98A02647D83285A36021911C6" } } }, @@ -6520,125 +6539,29 @@ } } }, - "/v1/quality-evaluation": { - "post": { - "tags": [ - "QualityEvaluation" - ], - "summary": "Submit an evaluation job", - "operationId": "submitQualityEvaluation", - "description": "Starts an evaluation job for the given segments. Returns a `poll_url` that can be used to retrieve the result.", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QualityEvaluationRequest" - }, - "example": { - "metadata": { - "source_language": "en", - "target_language": "de" - }, - "segments": [ - { - "source": "Our Q3 revenue came in 5% above forecast.", - "target": "Unser Q3-Umsatz lag 5 % unter der Prognose." - }, - { - "source": "Please share these results with your teams by Friday.", - "target": "Bitte teilen Sie diese Ergebnisse mit Ihrem Team." - } - ] - } - } - } - }, - "responses": { - "202": { - "description": "Job accepted. Use the returned `poll_url` to retrieve the result.", - "headers": { - "Retry-After": { - "description": "Suggested number of seconds to wait before polling.", - "schema": { - "type": "integer" - }, - "example": 5 - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QualityEvaluationJobCreated" - }, - "example": { - "job_id": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19", - "poll_url": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" - } - } - } - }, - "400": { - "description": "Request validation failed. Common causes:\n- `metadata.source_language`, `metadata.target_language`, or `segments` is missing or empty.\n- `segments` contains more than 500 entries.\n- A segment's `source` or `target` exceeds 10,000 characters.\n- The `source_language` / `target_language` combination is not supported.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QualityEvaluationApiError" - }, - "example": { - "message": "segments[0].source is required." - } - } - } - }, - "403": { - "description": "Authorization failed. Common causes:\n- The API key does not have access to the Quality Evaluation feature.\n- A free-tier key is used against the paid endpoint, or vice versa.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QualityEvaluationApiError" - }, - "example": { - "message": "Forbidden" - } - } - } - }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - } - }, - "security": [ - { - "auth_header": [] - } - ] - } - }, - "/v1/quality-evaluation/{job_id}": { + "/v1/quality-evaluations/{job_id}": { "get": { "tags": [ "QualityEvaluation" ], "summary": "Poll for the evaluation result", "operationId": "pollQualityEvaluation", - "description": "Returns the current state of an evaluation job. While the job is in progress the response contains only status information. Once complete the response includes the full evaluation report.", + "description": "Returns the current state of a quality evaluation. While the evaluation is in progress the response carries only status information; once it completes, the response carries the full report.\n\nEvaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). There is no public endpoint for starting one.", "parameters": [ { "name": "job_id", "in": "path", "required": true, - "description": "The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID.", + "description": "The unique ID of the quality evaluation, returned as `quality_evaluation_job_id` when the document was [uploaded for translation](/api-reference/document/upload-and-translate-a-document).", "schema": { "type": "string", - "format": "uuid", - "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "example": "04DE5AD98A02647D83285A36021911C6" } } ], "responses": { "200": { - "description": "Polling result. The response shape depends on the `status` field. `done` returns the full evaluation report; `error` returns error details.", + "description": "Polling result. The response shape depends on the `status` field. `done` carries the full report; `error` carries error details.", "content": { "application/json": { "schema": { @@ -6652,11 +6575,25 @@ ] }, "example": { - "job_id": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19", + "job_id": "04DE5AD98A02647D83285A36021911C6", "status": "done", "segments": [ { "segment_index": 0, + "source": "Our Q3 revenue came in 5% above forecast.", + "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.", + "entries": [ + { + "source_entry": "forecast", + "target_entry": "Prognose", + "ranges": [ + { + "start": 34, + "end": 42 + } + ] + } + ], "errors": [ { "type": "Accuracy", @@ -6680,6 +6617,8 @@ }, { "segment_index": 1, + "source": "Please share these results with your teams by Friday.", + "target": "Bitte teilen Sie diese Ergebnisse mit Ihrem Team.", "errors": [ { "type": "Accuracy", @@ -6714,27 +6653,13 @@ } ] } - ], - "summary": { - "overall_score": 72, - "granular_counts": { - "Accuracy": { - "Mistranslation": { - "Critical": 1, - "Minor": 1 - }, - "Omission": { - "Major": 1 - } - } - } - } + ] } } } }, "202": { - "description": "Job is still processing. Continue polling after the time suggested by the `Retry-After` header.", + "description": "The evaluation is still running. Continue polling after the time suggested by the `Retry-After` header.", "headers": { "Retry-After": { "description": "Suggested number of seconds to wait before polling again.", @@ -6750,14 +6675,14 @@ "$ref": "#/components/schemas/QualityEvaluationProcessing" }, "example": { - "job_id": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19", + "job_id": "04DE5AD98A02647D83285A36021911C6", "status": "processing" } } } }, "400": { - "description": "Invalid `job_id` format. The `job_id` must be a valid UUID.", + "description": "The `job_id` is not a well-formed identifier.", "content": { "application/json": { "schema": { @@ -6770,7 +6695,7 @@ } }, "404": { - "description": "Job not found. The `job_id` is well-formed but no job exists with that ID, or it has expired. Jobs are retained for 24 hours after reaching `done` or `error` state.", + "description": "No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluation/poll#report-retention).", "content": { "application/json": { "schema": { @@ -10944,82 +10869,6 @@ } } }, - "QualityEvaluationRequest": { - "type": "object", - "required": [ - "metadata", - "segments" - ], - "properties": { - "metadata": { - "type": "object", - "required": [ - "source_language", - "target_language" - ], - "description": "Job-level metadata.", - "properties": { - "source_language": { - "type": "string", - "description": "Language code of the source text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs).", - "example": "en" - }, - "target_language": { - "type": "string", - "description": "Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs).", - "example": "de" - } - } - }, - "segments": { - "type": "array", - "minItems": 1, - "maxItems": 500, - "description": "The segment pairs to evaluate. Up to 500 segments per request.", - "items": { - "type": "object", - "required": [ - "source", - "target" - ], - "properties": { - "source": { - "type": "string", - "maxLength": 10000, - "description": "The original text in the source language.", - "example": "Our Q3 revenue came in 5% above forecast." - }, - "target": { - "type": "string", - "maxLength": 10000, - "description": "The translated text in the target language.", - "example": "Unser Q3-Umsatz lag 5 % unter der Prognose." - } - } - } - } - } - }, - "QualityEvaluationJobCreated": { - "type": "object", - "required": [ - "job_id", - "poll_url" - ], - "properties": { - "job_id": { - "type": "string", - "format": "uuid", - "description": "The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result.", - "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" - }, - "poll_url": { - "type": "string", - "description": "Relative URL you can use to poll for the result.", - "example": "/v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" - } - } - }, "QualityEvaluationProcessing": { "type": "object", "required": [ @@ -11029,8 +10878,7 @@ "properties": { "job_id": { "type": "string", - "format": "uuid", - "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "example": "04DE5AD98A02647D83285A36021911C6" }, "status": { "type": "string", @@ -11047,14 +10895,12 @@ "required": [ "job_id", "status", - "segments", - "summary" + "segments" ], "properties": { "job_id": { "type": "string", - "format": "uuid", - "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "example": "04DE5AD98A02647D83285A36021911C6" }, "status": { "type": "string", @@ -11065,43 +10911,10 @@ }, "segments": { "type": "array", - "description": "One entry per submitted segment, in request order.", + "description": "One entry per evaluated segment of the document, in reading order.", "items": { "$ref": "#/components/schemas/QualityEvaluationSegment" } - }, - "summary": { - "type": "object", - "required": [ - "overall_score", - "granular_counts" - ], - "description": "Aggregate quality results across all segments.", - "properties": { - "overall_score": { - "type": "integer", - "minimum": 0, - "maximum": 100, - "description": "Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary).", - "example": 72 - }, - "granular_counts": { - "type": "object", - "description": "Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts.", - "additionalProperties": true, - "example": { - "Accuracy": { - "Mistranslation": { - "Critical": 1, - "Minor": 1 - }, - "Omission": { - "Major": 1 - } - } - } - } - } } } }, @@ -11116,8 +10929,7 @@ "properties": { "job_id": { "type": "string", - "format": "uuid", - "example": "f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19" + "example": "04DE5AD98A02647D83285A36021911C6" }, "status": { "type": "string", @@ -11156,9 +10968,26 @@ "properties": { "segment_index": { "type": "integer", - "description": "Zero-based index matching the position of this segment in the request.", + "description": "Zero-based index of this segment within the document, in reading order.", "example": 0 }, + "source": { + "type": "string", + "description": "The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", + "example": "Our Q3 revenue came in 5% above forecast." + }, + "target": { + "type": "string", + "description": "The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", + "example": "Unser Q3-Umsatz lag 5 % unter der Prognose." + }, + "entries": { + "type": "array", + "description": "Glossary entries applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no entry was applied.", + "items": { + "$ref": "#/components/schemas/QualityEvaluationGlossaryEntry" + } + }, "errors": { "type": "array", "description": "Quality issues identified in this segment. Empty if no issues were found.", @@ -11168,6 +10997,34 @@ } } }, + "QualityEvaluationGlossaryEntry": { + "type": "object", + "description": "A glossary entry that was applied to the segment's translation.", + "required": [ + "source_entry", + "target_entry", + "ranges" + ], + "properties": { + "source_entry": { + "type": "string", + "description": "The entry's source term, as defined in the glossary.", + "example": "forecast" + }, + "target_entry": { + "type": "string", + "description": "The entry's target term, as applied to the translation.", + "example": "Prognose" + }, + "ranges": { + "type": "array", + "description": "Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", + "items": { + "$ref": "#/components/schemas/QualityEvaluationSpan" + } + } + } + }, "QualityEvaluationIssue": { "type": "object", "required": [ @@ -11186,7 +11043,8 @@ "Accuracy", "Fluency", "Style", - "Miscellaneous" + "Miscellaneous", + "InternalTQEError" ], "example": "Accuracy" }, @@ -11207,7 +11065,8 @@ "Inconsistency", "Character encoding", "Awkward", - "Inconsistent style" + "Inconsistent style", + "SegmentTooLarge" ], "example": "Mistranslation" }, @@ -11217,7 +11076,8 @@ "enum": [ "Critical", "Major", - "Minor" + "Minor", + "Unclear (Check Needed)" ], "example": "Critical" }, @@ -11228,14 +11088,14 @@ }, "source_spans": { "type": "array", - "description": "Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges).", + "description": "Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", "items": { "$ref": "#/components/schemas/QualityEvaluationSpan" } }, "target_spans": { "type": "array", - "description": "Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges).", + "description": "Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", "items": { "$ref": "#/components/schemas/QualityEvaluationSpan" } @@ -11248,7 +11108,7 @@ "start", "end" ], - "description": "A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges).", + "description": "A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", "properties": { "start": { "type": "integer", diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 0887da1d..27d453d3 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -115,7 +115,7 @@ tags: description: Endpoints for organization administrators to manage API keys and retrieve usage analytics. - name: QualityEvaluation description: |- - **Closed alpha.** Evaluate translation quality. Submit source/target segment pairs and retrieve per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs. + **Beta.** Retrieve a quality evaluation report for a document DeepL has translated. Reports are requested with `enable_quality_evaluation` on `POST /v2/document` and polled here. A report lists per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs. x-hideTryItPanel: true x-codeSamples: false paths: @@ -910,6 +910,13 @@ paths: file: '@document.docx' translation_memory_id: '[yourTranslationMemoryId]' translation_memory_threshold: 75 + QualityEvaluation: + summary: Requesting a quality evaluation report (beta) + value: + source_lang: EN + target_lang: DE + file: '@document.docx' + enable_quality_evaluation: true schema: type: object required: @@ -986,6 +993,15 @@ paths: Only supported for `docx` and `pdf` output. For all other output formats the parameter is ignored and the document is returned without a watermark. type: boolean default: false + enable_quality_evaluation: + description: |- + (beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) with it for a per-segment report of translation issues. The translation itself is unaffected. + + **Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) only. + + Rejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`. + type: boolean + default: false enable_beta_languages: description: |- This parameter is maintained for backward compatibility and has no effect. @@ -1021,6 +1037,11 @@ paths: this particular document. type: string example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A + quality_evaluation_job_id: + description: |- + (beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll). + type: string + example: 04DE5AD98A02647D83285A36021911C6 example: document_id: 04DE5AD98A02647D83285A36021911C6 document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A @@ -4606,94 +4627,28 @@ paths: $ref: '#/components/responses/NotFound' "429": $ref: '#/components/responses/TooManyRequests' - /v1/quality-evaluation: - post: - tags: - - QualityEvaluation - summary: Submit an evaluation job - operationId: submitQualityEvaluation - description: |- - Starts an evaluation job for the given segments. Returns a `poll_url` that can be used to retrieve the result. - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/QualityEvaluationRequest' - example: - metadata: - source_language: en - target_language: de - segments: - - source: Our Q3 revenue came in 5% above forecast. - target: Unser Q3-Umsatz lag 5 % unter der Prognose. - - source: Please share these results with your teams by Friday. - target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. - responses: - '202': - description: Job accepted. Use the returned `poll_url` to retrieve the result. - headers: - Retry-After: - description: Suggested number of seconds to wait before polling. - schema: - type: integer - example: 5 - content: - application/json: - schema: - $ref: '#/components/schemas/QualityEvaluationJobCreated' - example: - job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 - poll_url: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 - '400': - description: |- - Request validation failed. Common causes: - - `metadata.source_language`, `metadata.target_language`, or `segments` is missing or empty. - - `segments` contains more than 500 entries. - - A segment's `source` or `target` exceeds 10,000 characters. - - The `source_language` / `target_language` combination is not supported. - content: - application/json: - schema: - $ref: '#/components/schemas/QualityEvaluationApiError' - example: - message: segments[0].source is required. - '403': - description: |- - Authorization failed. Common causes: - - The API key does not have access to the Quality Evaluation feature. - - A free-tier key is used against the paid endpoint, or vice versa. - content: - application/json: - schema: - $ref: '#/components/schemas/QualityEvaluationApiError' - example: - message: Forbidden - '429': - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v1/quality-evaluation/{job_id}: + /v1/quality-evaluations/{job_id}: get: tags: - QualityEvaluation summary: Poll for the evaluation result operationId: pollQualityEvaluation description: |- - Returns the current state of an evaluation job. While the job is in progress the response contains only status information. Once complete the response includes the full evaluation report. + Returns the current state of a quality evaluation. While the evaluation is in progress the response carries only status information; once it completes, the response carries the full report. + + Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). There is no public endpoint for starting one. parameters: - name: job_id in: path required: true - description: The job identifier returned by `POST /v1/quality-evaluation`. Must be a valid UUID. + description: The unique ID of the quality evaluation, returned as `quality_evaluation_job_id` when the document was [uploaded for translation](/api-reference/document/upload-and-translate-a-document). schema: type: string - format: uuid - example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + example: 04DE5AD98A02647D83285A36021911C6 responses: '200': description: |- - Polling result. The response shape depends on the `status` field. `done` returns the full evaluation report; `error` returns error details. + Polling result. The response shape depends on the `status` field. `done` carries the full report; `error` carries error details. content: application/json: schema: @@ -4701,10 +4656,18 @@ paths: - $ref: '#/components/schemas/QualityEvaluationDone' - $ref: '#/components/schemas/QualityEvaluationFailed' example: - job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + job_id: 04DE5AD98A02647D83285A36021911C6 status: done segments: - segment_index: 0 + source: Our Q3 revenue came in 5% above forecast. + target: Unser Q3-Umsatz lag 5 % unter der Prognose. + entries: + - source_entry: forecast + target_entry: Prognose + ranges: + - start: 34 + end: 42 errors: - type: Accuracy sub_type: Mistranslation @@ -4717,6 +4680,8 @@ paths: - start: 20 end: 29 - segment_index: 1 + source: Please share these results with your teams by Friday. + target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. errors: - type: Accuracy sub_type: Omission @@ -4736,17 +4701,8 @@ paths: target_spans: - start: 38 end: 48 - summary: - overall_score: 72 - granular_counts: - Accuracy: - Mistranslation: - Critical: 1 - Minor: 1 - Omission: - Major: 1 '202': - description: Job is still processing. Continue polling after the time suggested by the `Retry-After` header. + description: The evaluation is still running. Continue polling after the time suggested by the `Retry-After` header. headers: Retry-After: description: Suggested number of seconds to wait before polling again. @@ -4758,10 +4714,10 @@ paths: schema: $ref: '#/components/schemas/QualityEvaluationProcessing' example: - job_id: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + job_id: 04DE5AD98A02647D83285A36021911C6 status: processing '400': - description: Invalid `job_id` format. The `job_id` must be a valid UUID. + description: The `job_id` is not a well-formed identifier. content: application/json: schema: @@ -4770,7 +4726,7 @@ paths: message: job_id must be a valid UUID. '404': description: |- - Job not found. The `job_id` is well-formed but no job exists with that ID, or it has expired. Jobs are retained for 24 hours after reaching `done` or `error` state. + No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluation/poll#report-retention). content: application/json: schema: @@ -8262,63 +8218,6 @@ components: description: Per-target processing results, in the same order as the `targets` array. items: $ref: '#/components/schemas/VoiceTranslateJobTargetResult' - QualityEvaluationRequest: - type: object - required: - - metadata - - segments - properties: - metadata: - type: object - required: - - source_language - - target_language - description: Job-level metadata. - properties: - source_language: - type: string - description: Language code of the source text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs). - example: en - target_language: - type: string - description: Language code of the translated text. See [Supported language pairs](/api-reference/quality-evaluation/submit#supported-language-pairs). - example: de - segments: - type: array - minItems: 1 - maxItems: 500 - description: The segment pairs to evaluate. Up to 500 segments per request. - items: - type: object - required: - - source - - target - properties: - source: - type: string - maxLength: 10000 - description: The original text in the source language. - example: Our Q3 revenue came in 5% above forecast. - target: - type: string - maxLength: 10000 - description: The translated text in the target language. - example: Unser Q3-Umsatz lag 5 % unter der Prognose. - QualityEvaluationJobCreated: - type: object - required: - - job_id - - poll_url - properties: - job_id: - type: string - format: uuid - description: The job identifier. Use it with `GET /v1/quality-evaluation/{job_id}` to poll for the result. - example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 - poll_url: - type: string - description: Relative URL you can use to poll for the result. - example: /v1/quality-evaluation/f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 QualityEvaluationProcessing: type: object required: @@ -8327,8 +8226,7 @@ components: properties: job_id: type: string - format: uuid - example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: @@ -8341,12 +8239,10 @@ components: - job_id - status - segments - - summary properties: job_id: type: string - format: uuid - example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: @@ -8354,33 +8250,9 @@ components: example: done segments: type: array - description: One entry per submitted segment, in request order. + description: One entry per evaluated segment of the document, in reading order. items: $ref: '#/components/schemas/QualityEvaluationSegment' - summary: - type: object - required: - - overall_score - - granular_counts - description: Aggregate quality results across all segments. - properties: - overall_score: - type: integer - minimum: 0 - maximum: 100 - description: Overall translation quality, from 0 (lowest) to 100 (highest). See [Summary](/api-reference/quality-evaluation/poll#summary). - example: 72 - granular_counts: - type: object - description: Nested counts keyed by `type`, then `sub_type`, then `severity`. Leaf values are integer counts. - additionalProperties: true - example: - Accuracy: - Mistranslation: - Critical: 1 - Minor: 1 - Omission: - Major: 1 QualityEvaluationFailed: title: Error type: object @@ -8391,8 +8263,7 @@ components: properties: job_id: type: string - format: uuid - example: f3a8c5e1-9b7d-4e62-a1c4-8f5d2b6e3c19 + example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: @@ -8420,13 +8291,47 @@ components: properties: segment_index: type: integer - description: Zero-based index matching the position of this segment in the request. + description: Zero-based index of this segment within the document, in reading order. example: 0 + source: + type: string + description: The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). + example: Our Q3 revenue came in 5% above forecast. + target: + type: string + description: The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). + example: Unser Q3-Umsatz lag 5 % unter der Prognose. + entries: + type: array + description: Glossary entries applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no entry was applied. + items: + $ref: '#/components/schemas/QualityEvaluationGlossaryEntry' errors: type: array description: Quality issues identified in this segment. Empty if no issues were found. items: $ref: '#/components/schemas/QualityEvaluationIssue' + QualityEvaluationGlossaryEntry: + type: object + description: A glossary entry that was applied to the segment's translation. + required: + - source_entry + - target_entry + - ranges + properties: + source_entry: + type: string + description: The entry's source term, as defined in the glossary. + example: forecast + target_entry: + type: string + description: The entry's target term, as applied to the translation. + example: Prognose + ranges: + type: array + description: Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). + items: + $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationIssue: type: object required: @@ -8445,6 +8350,7 @@ components: - Fluency - Style - Miscellaneous + - InternalTQEError example: Accuracy sub_type: type: string @@ -8464,6 +8370,7 @@ components: - Character encoding - Awkward - Inconsistent style + - SegmentTooLarge example: Mistranslation severity: type: string @@ -8472,6 +8379,7 @@ components: - Critical - Major - Minor + - Unclear (Check Needed) example: Critical explanation: type: string @@ -8479,12 +8387,12 @@ components: example: "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications." source_spans: type: array - description: Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). + description: Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' target_spans: type: array - description: Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). + description: Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationSpan: @@ -8492,7 +8400,7 @@ components: required: - start - end - description: A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [About span ranges](/api-reference/quality-evaluation/poll#about-span-ranges). + description: A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). properties: start: type: integer diff --git a/api-reference/quality-evaluation.mdx b/api-reference/quality-evaluation.mdx deleted file mode 100644 index 616be8ca..00000000 --- a/api-reference/quality-evaluation.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Evaluate translation quality" -description: "API reference for detecting translation quality issues with the DeepL API." ---- - - - **Closed alpha.** This API may change without notice and is only available to select DeepL customers. See [alpha and beta features](/docs/resources/alpha-and-beta-features) for details. To request access, contact your customer success manager. - - -## Overview - -Identify quality issues with your translations through a two-step process: - -1. [**Submit an evaluation job**](/api-reference/quality-evaluation/submit) -2. [**Poll for the result**](/api-reference/quality-evaluation/poll) - -## Limits - -| **Limit** | **Value** | -|---|---:| -| Segments per request | 500 | -| Characters per segment (`source` or `target`) | 10,000 | - -### Rate limits - -| **Endpoint** | **Limit** | -|---|---| -| `POST /v1/quality-evaluation` | 100 requests per minute per API key | -| `GET /v1/quality-evaluation/{job_id}` | 1,000 requests per minute per API key | - -Exceeding either limit returns `429 Too Many Requests`. - -## Job retention - -Job results are retained for 24 hours after the job reaches `done` or `error` state. After that, the `GET` endpoint returns `404 Not Found` for that `job_id`. diff --git a/api-reference/quality-evaluation/poll.mdx b/api-reference/quality-evaluation/poll.mdx index 1a3579e9..3f999a60 100644 --- a/api-reference/quality-evaluation/poll.mdx +++ b/api-reference/quality-evaluation/poll.mdx @@ -1,29 +1,77 @@ --- -openapi: get /v1/quality-evaluation/{job_id} +openapi: get /v1/quality-evaluations/{job_id} +tag: "BETA" title: "Poll for the evaluation result" -description: "Poll an evaluation job for its status, and retrieve the full quality evaluation report once the job completes." +description: "Poll a document's quality evaluation for its status and retrieve the per-segment report of translation issues once it completes." --- -See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits. + + Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select DeepL customers only. To request access, contact your customer success manager. + -### Summary +Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document), which returns a `quality_evaluation_job_id`. That is the unique ID of the evaluation, and the value this endpoint takes. There is no public endpoint for starting an evaluation. For the end-to-end flow, see [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation). -The `summary` object aggregates the results across all segments: +Evaluations resolve only within the account that requested them. A job ID belonging to another account returns `404`, the same response as an unknown ID. -* `overall_score` rates the overall translation quality from 0 (lowest) to 100 (highest). The score is based on the severity of detected issues and adjusts for the length of the text, so a single issue has less impact on a longer translation than on a shorter one. -* `granular_counts` breaks down the number of issues, nested by `type`, then `sub_type`, then `severity`. +## Status values -### Severity values +| **Value** | **HTTP status** | **Response body** | +|---|---|---| +| `processing` | `202` | `job_id` and `status` only. The `Retry-After` header carries the suggested number of seconds before the next poll. | +| `done` | `200` | The full report in `segments`. | +| `error` | `200` | An `error` object. The evaluation produced no report and will not produce one later. | -| **severity** | **Description** | +A completed evaluation and a failed one both return `200`, so `status` rather than the HTTP status code distinguishes them. A malformed `job_id` returns `400` without reaching an evaluation. + +`error.code` is currently always `evaluation_failed`, so the response does not distinguish one cause of failure from another. + +## Segment text + +A report carries one entry in `segments` per evaluated segment of the document, in reading order, including segments where no issue was found. On those, `errors` is an empty array. + +`segment_index` is that reading-order position. It is not a durable handle: re-translating the same document can produce a different segmentation. + +`source` and `target` hold the segment text as the evaluation read it, which is DeepL's own segmentation of the document with inline formatting tags removed. This text does not byte-match the text in the uploaded or translated file, and segment boundaries do not necessarily correspond to the paragraphs or sentences in the document. Span offsets index these two strings, not the uploaded or translated file. + +Both fields are omitted when the text is unavailable for a segment. An issue on such a segment still carries its spans, but there is no text in the response to resolve them against. + +`entries` lists the glossary entries applied to a segment when the document was translated, and is omitted for segments where none was applied. Each entry gives the [glossary](/docs/customize/managing-glossaries) term pair and the spans in `target` where the target term was applied. + +## Span ranges + +Each span describes a half-open interval over the segment's source or target text. `start` is the index of the first Unicode code point in the span; `end` is one past the last. The span covers the substring `text[start:end]` in Python-style slicing, and its length is `end - start`. For example: + +```text +target: Unser Q3-Umsatz lag 5 % unter der Prognose. +``` + +A target span of `{ "start": 20, "end": 29 }` covers `target[20:29]`, the 9 code points `"5 % unter"`. Offsets count code points, not UTF-16 code units, so a language whose characters fall outside the Basic Multilingual Plane indexes differently than a UTF-16 string length would suggest. + +- `source_spans` and `target_spans` are always present on an issue. If no span applies to that side, the value is an empty array +- Within a single issue, the ranges in `source_spans` (and in `target_spans`) are sorted by `start` and do not overlap +- Different issues may cover the same part of a segment +- `ranges` on a glossary entry follows the same convention and indexes into `target` + +## Severity values + +The `severity` field on an issue takes one of four values. + +| **Value** | **Description** | |---|---| | `Critical` | Renders the content unusable or significantly changes its meaning. For example, the meaning is reversed, important information is missing, or the content is unsuitable for the intended audience. | | `Major` | Misleads the reader or significantly alters the meaning. The general idea is clear, but specific details are wrong, terminology is incorrect, or grammar issues make the text hard to understand. | | `Minor` | Does not make the text unreadable, but can make it harder to understand and less appealing. | +| `Unclear (Check Needed)` | A possible issue that the segment alone does not provide enough context to confirm. | + +## Type and sub-type values + +Every issue carries a `type`, the top-level category, and a `sub_type`, which narrows it within that type. The five types and their sub-types are listed below. -### Type and sub-type values + + `type`, `sub_type`, and `severity` are open strings on the wire, not closed sets. Match the values below rather than switching exhaustively over them, so an unlisted value does not break your client. + -#### Accuracy +### Accuracy | **sub_type** | **Description** | |---|---| @@ -34,7 +82,7 @@ The `summary` object aggregates the results across all segments: | `Under-translation` | The target is less specific than the source. | | `Untranslated text` | Content that should have been translated has been left untranslated. | -#### Fluency +### Fluency | **sub_type** | **Description** | |---|---| @@ -45,27 +93,46 @@ The `summary` object aggregates the results across all segments: | `Inconsistency` | The text is not internally consistent. For example, using two different abbreviations for the same term. | | `Character encoding` | Characters are garbled due to incorrect application of an encoding. | -#### Style +### Style | **sub_type** | **Description** | |---|---| | `Awkward` | The text is written in an awkward style. | | `Inconsistent style` | The text uses inconsistent stylistic conventions across sections. | -#### Miscellaneous +### Miscellaneous -Errors that do not fall into the other categories, but are nonetheless clearly identifiable as mistakes. +| **sub_type** | **Description** | +|---|---| +| Not enumerated | An error that does not fall into the other categories but is nonetheless clearly identifiable as a mistake. The sub-types of this type are not a fixed set, so read `sub_type` as free text. | -### About span ranges +### InternalTQEError -Each span describes a half-open interval over the segment's source or target text. `start` is the index of the first Unicode code point in the span; `end` is one past the last. The span covers the substring `text[start:end]` in Python-style slicing, and its length is `end - start`. For example: +| **sub_type** | **Description** | +|---|---| +| `SegmentTooLarge` | The segment's source and target exceed 10,000 characters combined, so it was not analyzed. Reported with severity `Critical`. | -```text -target: Unser Q3-Umsatz lag 5 % unter der Prognose. -``` +An issue of this type reports that a segment could not be evaluated rather than a defect in the translation. The rest of the document is evaluated normally. + +## Supported language pairs + +| **Source language** | **Target languages** | +|---|---| +| German (`DE`) | English (`EN-GB`, `EN-US`) | +| English (`EN`) | German (`DE`), Spanish (`ES`, `ES-419`), French (`FR`), Italian (`IT`), Japanese (`JA`), Korean (`KO`) | +| Spanish (`ES`) | English (`EN-GB`, `EN-US`) | +| French (`FR`) | English (`EN-GB`, `EN-US`) | +| Italian (`IT`) | English (`EN-GB`, `EN-US`) | +| Japanese (`JA`) | English (`EN-GB`, `EN-US`), Korean (`KO`), Chinese Simplified (`ZH-HANS`), Chinese Traditional (`ZH-HANT`) | +| Korean (`KO`) | English (`EN-GB`, `EN-US`), Japanese (`JA`) | +| Chinese (`ZH`) | Japanese (`JA`) | + +Requesting an evaluation for a pair that is not listed is rejected with `400` when the document is uploaded, so an evaluation only ever exists for a supported pair. See [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document). + +## Rate limit + +This endpoint accepts 1,000 requests per minute per API key. Exceeding it returns `429 Too Many Requests`. -A target span of `{ "start": 20, "end": 29 }` covers `target[20:29]`, the 9-character substring `"5 % unter"`. +## Report retention -* `source_spans` and `target_spans` are always present in the response. If no span is available for that side, the value is an empty array. -* Within a single issue, ranges in `source_spans` (and `target_spans`) are sorted by `start` and do not overlap. -* Different issues may highlight the same part of a segment. +A report is retained for 24 hours after its evaluation reaches `done` or `error`. After that, this endpoint returns `404 Not Found` for that job ID. diff --git a/api-reference/quality-evaluation/submit.mdx b/api-reference/quality-evaluation/submit.mdx deleted file mode 100644 index 7552cc89..00000000 --- a/api-reference/quality-evaluation/submit.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -openapi: post /v1/quality-evaluation -title: "Submit an evaluation job" -description: "Submit translated segments for quality evaluation and receive a poll URL for retrieving the report." ---- - -See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits. - -### Supported language pairs - -| **Source Language** | **Target Languages** | -|---|---| -| German (`de`) | English (`en-gb`, `en-us`) | -| English (`en`) | German (`de`), Spanish (`es`, `es-419`), French (`fr`), Italian (`it`), Japanese (`ja`), Korean (`ko`) | -| Spanish (`es`) | English (`en-gb`, `en-us`) | -| French (`fr`) | English (`en-gb`, `en-us`) | -| Italian (`it`) | English (`en-gb`, `en-us`) | -| Japanese (`ja`) | English (`en-gb`, `en-us`), Korean (`ko`), Chinese Simplified (`zh-hans`), Chinese Traditional (`zh-hant`) | -| Korean (`ko`) | English (`en-gb`, `en-us`), Japanese (`ja`) | -| Chinese (`zh`) | Japanese (`ja`) | diff --git a/docs.json b/docs.json index b4873789..5df27eaf 100644 --- a/docs.json +++ b/docs.json @@ -231,6 +231,14 @@ ], "drilldown": false }, + { + "group": "Quality Evaluation", + "tag": "BETA", + "pages": [ + "api-reference/quality-evaluation/poll" + ], + "drilldown": false + }, { "group": "Write", "pages": [ @@ -614,6 +622,14 @@ "source": "/api-reference/document", "destination": "/api-reference/document/upload-and-translate-a-document" }, + { + "source": "/api-reference/quality-evaluation", + "destination": "/api-reference/quality-evaluation/poll" + }, + { + "source": "/api-reference/quality-evaluation/submit", + "destination": "/api-reference/quality-evaluation/poll" + }, { "source": "/api-reference/multilingual-glossaries", "destination": "/api-reference/multilingual-glossaries/create-a-glossary" diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 79f4b1ef..0c041752 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -1,8 +1,9 @@ --- title: "Document translations" -description: "Handle file size limits, status codes, and error details when translating documents with the DeepL API." +description: "Handle file size limits, status codes, quality evaluation reports, and error details when translating documents with the DeepL API." mode: "wide" public: true +covers: [Quality Evaluation] --- Below you will find general guidance on how to handle status codes and error details to ensure a smooth document translation experience. @@ -77,6 +78,73 @@ Translation time depends on document size and server load: small documents typic ### Using glossaries with documents You can apply a glossary to a document translation with the `glossary_id` parameter (or up to 5 glossaries with `glossary_ids`). This requires the `source_lang` parameter to be set, and the glossary's language pair has to match the language pair of the request. +### Requesting a quality evaluation +A quality evaluation is a report on the translation DeepL just produced: for each segment of the document it lists the issues it detected, such as mistranslations, omissions, and fluency or style problems, with a severity and the character range each issue applies to. Use it to target human review at the segments that need it instead of reviewing the whole document. + + + Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select customers only. To have it enabled for your account, contact your customer success manager; until then, opting in returns HTTP 403. + + +Add [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document) to the upload. Two limits apply, and both are checked before the upload is accepted: only `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 files can be evaluated, and quality evaluation covers fewer language pairs than translation does. Check the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) before you opt in. + +An ineligible file type or an unsupported language pair is rejected with HTTP 400 before the translation starts, so nothing is translated and nothing is billed. Opting in never puts the translation itself at risk. + +```bash +curl -X POST https://api.deepl.com/v2/document \ + --header "Authorization: DeepL-Auth-Key $API_KEY" \ + --form 'source_lang=EN' \ + --form 'target_lang=DE' \ + --form 'file=@quarterly-report.docx' \ + --form 'enable_quality_evaluation=true' +``` + +The upload response carries a `quality_evaluation_job_id` alongside the usual document fields. It is the unique ID of the evaluation, and the value you poll with to retrieve the report: + +```json +{ + "document_id": "04DE5AD98A02647D83285A36021911C6", + "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A", + "quality_evaluation_job_id": "04DE5AD98A02647D83285A36021911C6" +} +``` + +Keep polling the [status endpoint](/api-reference/document/check-document-status) and downloading the translated document as you normally would. The report is a separate job, so poll for it separately: + +```bash +curl https://api.deepl.com/v1/quality-evaluations/04DE5AD98A02647D83285A36021911C6 \ + --header "Authorization: DeepL-Auth-Key $API_KEY" +``` + +While the evaluation is running you get HTTP 202 and `"status": "processing"`; wait the number of seconds in the `Retry-After` header and poll again. Expect this for a while after the translated document is ready, because the evaluation only starts once there is a translation to evaluate. + +A finished evaluation returns HTTP 200 whether it succeeded or failed, so branch on `status` rather than the status code: `done` carries the report, and `error` means the evaluation could not be produced, for example because the language pair isn't supported. + +```json +{ + "job_id": "04DE5AD98A02647D83285A36021911C6", + "status": "done", + "segments": [ + { + "segment_index": 0, + "source": "Our Q3 revenue came in 5% above forecast.", + "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.", + "errors": [ + { + "type": "Accuracy", + "sub_type": "Mistranslation", + "severity": "Critical", + "explanation": "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This reverses the meaning.", + "source_spans": [{ "start": 23, "end": 31 }], + "target_spans": [{ "start": 20, "end": 29 }] + } + ] + } + ] +} +``` + +Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluation/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the glossary entries a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluation/poll). + ### Document format conversions By default, the translated document comes back in the same format as the input. Two conversions differ: diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index cbcc2d94..69631417 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,12 @@ rss: true +## September 20 - Quality Evaluation for Document Translation (Beta) +- A **quality evaluation** is a report on a translation DeepL has produced: for each segment it lists detected issues such as mistranslations, omissions, and fluency or style problems, with a severity and the character range the issue applies to. Use it to target human review at the segments that need it. +- Request one by setting `enable_quality_evaluation=true` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). The upload response then returns a `quality_evaluation_job_id`, which you poll at [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) to retrieve the report. See [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation) for the full flow. +- Reports cover `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and a subset of the language pairs translation supports. Each report also returns the source and translated text of every segment, plus the glossary entries that were applied to it. +- In beta and available to select customers only. To have it enabled for your account, contact your customer success manager. + ## September 11 - Speaker Match Voice for the Voice API - **Speaker match** is a new voice option for [Voice API](/docs/voice/overview) translated speech: instead of one of the preset voices, the synthesized audio uses a voice close to the original speaker's. Set [`target_media_voice`](/api-reference/voice/request-session) to `match` on the session request. - Speaker match is only available for target languages whose translated speech is provided by DeepL, not for languages provided through external service partners. Requesting it for any other target language is not an error: that language falls back to a preset voice. See the [supported languages table](/docs/voice/supported-voice-languages) for the full list. diff --git a/standards/ia.yaml b/standards/ia.yaml index b5cdb052..729722d9 100644 --- a/standards/ia.yaml +++ b/standards/ia.yaml @@ -58,6 +58,6 @@ families: - {name: Languages, tags: [MetaInformation]} QualityEvaluation: - narrative_home: unplaced # alpha — human decides (maybe under Translate) + narrative_home: Translate # reports are requested via document translation groups: - {name: Quality Evaluation, tags: [QualityEvaluation]} From 5919b091a4eda5fa81ec392a9e834c1190a5ebfe Mon Sep 17 00:00:00 2001 From: Thomas Neil Date: Wed, 23 Sep 2026 13:02:09 +0300 Subject: [PATCH 2/3] docs: align quality evaluation response fields Co-authored-by: Cursor --- api-reference/openapi.json | 42 ++++++----- api-reference/openapi.yaml | 39 +++++++---- api-reference/quality-evaluation/poll.mdx | 69 +++++++------------ docs/best-practices/document-translations.mdx | 20 +++++- docs/resources/roadmap-and-release-notes.mdx | 2 +- 5 files changed, 92 insertions(+), 80 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index eea9b13f..9cbb9197 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -6580,12 +6580,13 @@ "segments": [ { "segment_index": 0, + "segment_score": 38.5, "source": "Our Q3 revenue came in 5% above forecast.", "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.", - "entries": [ + "applied_glossary_term_pairs": [ { - "source_entry": "forecast", - "target_entry": "Prognose", + "source_term": "forecast", + "target_term": "Prognose", "ranges": [ { "start": 34, @@ -6617,6 +6618,7 @@ }, { "segment_index": 1, + "segment_score": 62, "source": "Please share these results with your teams by Friday.", "target": "Bitte teilen Sie diese Ergebnisse mit Ihrem Team.", "errors": [ @@ -10963,6 +10965,7 @@ "type": "object", "required": [ "segment_index", + "segment_score", "errors" ], "properties": { @@ -10971,6 +10974,14 @@ "description": "Zero-based index of this segment within the document, in reading order.", "example": 0 }, + "segment_score": { + "type": "number", + "format": "float", + "minimum": 0, + "maximum": 100, + "description": "Quality score for this segment, where 0 is lowest and 100 is highest.", + "example": 38.5 + }, "source": { "type": "string", "description": "The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", @@ -10981,11 +10992,11 @@ "description": "The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", "example": "Unser Q3-Umsatz lag 5 % unter der Prognose." }, - "entries": { + "applied_glossary_term_pairs": { "type": "array", - "description": "Glossary entries applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no entry was applied.", + "description": "Glossary term pairs applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no term pair was applied.", "items": { - "$ref": "#/components/schemas/QualityEvaluationGlossaryEntry" + "$ref": "#/components/schemas/QualityEvaluationAppliedGlossaryTermPair" } }, "errors": { @@ -10997,23 +11008,23 @@ } } }, - "QualityEvaluationGlossaryEntry": { + "QualityEvaluationAppliedGlossaryTermPair": { "type": "object", - "description": "A glossary entry that was applied to the segment's translation.", + "description": "A glossary term pair that was applied to the segment's translation.", "required": [ - "source_entry", - "target_entry", + "source_term", + "target_term", "ranges" ], "properties": { - "source_entry": { + "source_term": { "type": "string", - "description": "The entry's source term, as defined in the glossary.", + "description": "The source term, as defined in the glossary.", "example": "forecast" }, - "target_entry": { + "target_term": { "type": "string", - "description": "The entry's target term, as applied to the translation.", + "description": "The target term, as applied to the translation.", "example": "Prognose" }, "ranges": { @@ -11076,8 +11087,7 @@ "enum": [ "Critical", "Major", - "Minor", - "Unclear (Check Needed)" + "Minor" ], "example": "Critical" }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 27d453d3..668c0bd9 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4660,11 +4660,12 @@ paths: status: done segments: - segment_index: 0 + segment_score: 38.5 source: Our Q3 revenue came in 5% above forecast. target: Unser Q3-Umsatz lag 5 % unter der Prognose. - entries: - - source_entry: forecast - target_entry: Prognose + applied_glossary_term_pairs: + - source_term: forecast + target_term: Prognose ranges: - start: 34 end: 42 @@ -4680,6 +4681,7 @@ paths: - start: 20 end: 29 - segment_index: 1 + segment_score: 62 source: Please share these results with your teams by Friday. target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. errors: @@ -8287,12 +8289,20 @@ components: type: object required: - segment_index + - segment_score - errors properties: segment_index: type: integer description: Zero-based index of this segment within the document, in reading order. example: 0 + segment_score: + type: number + format: float + minimum: 0 + maximum: 100 + description: Quality score for this segment, where 0 is lowest and 100 is highest. + example: 38.5 source: type: string description: The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). @@ -8301,31 +8311,31 @@ components: type: string description: The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). example: Unser Q3-Umsatz lag 5 % unter der Prognose. - entries: + applied_glossary_term_pairs: type: array - description: Glossary entries applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no entry was applied. + description: Glossary term pairs applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no term pair was applied. items: - $ref: '#/components/schemas/QualityEvaluationGlossaryEntry' + $ref: '#/components/schemas/QualityEvaluationAppliedGlossaryTermPair' errors: type: array description: Quality issues identified in this segment. Empty if no issues were found. items: $ref: '#/components/schemas/QualityEvaluationIssue' - QualityEvaluationGlossaryEntry: + QualityEvaluationAppliedGlossaryTermPair: type: object - description: A glossary entry that was applied to the segment's translation. + description: A glossary term pair that was applied to the segment's translation. required: - - source_entry - - target_entry + - source_term + - target_term - ranges properties: - source_entry: + source_term: type: string - description: The entry's source term, as defined in the glossary. + description: The source term, as defined in the glossary. example: forecast - target_entry: + target_term: type: string - description: The entry's target term, as applied to the translation. + description: The target term, as applied to the translation. example: Prognose ranges: type: array @@ -8379,7 +8389,6 @@ components: - Critical - Major - Minor - - Unclear (Check Needed) example: Critical explanation: type: string diff --git a/api-reference/quality-evaluation/poll.mdx b/api-reference/quality-evaluation/poll.mdx index 3f999a60..13d086bb 100644 --- a/api-reference/quality-evaluation/poll.mdx +++ b/api-reference/quality-evaluation/poll.mdx @@ -31,11 +31,13 @@ A report carries one entry in `segments` per evaluated segment of the document, `segment_index` is that reading-order position. It is not a durable handle: re-translating the same document can produce a different segmentation. +`segment_score` rates the translation quality of that segment from 0 (lowest) to 100 (highest). It is always present in a completed report. + `source` and `target` hold the segment text as the evaluation read it, which is DeepL's own segmentation of the document with inline formatting tags removed. This text does not byte-match the text in the uploaded or translated file, and segment boundaries do not necessarily correspond to the paragraphs or sentences in the document. Span offsets index these two strings, not the uploaded or translated file. Both fields are omitted when the text is unavailable for a segment. An issue on such a segment still carries its spans, but there is no text in the response to resolve them against. -`entries` lists the glossary entries applied to a segment when the document was translated, and is omitted for segments where none was applied. Each entry gives the [glossary](/docs/customize/managing-glossaries) term pair and the spans in `target` where the target term was applied. +`applied_glossary_term_pairs` lists the glossary term pairs applied to a segment when the document was translated. It is omitted for segments where no glossary term pair was applied. Each item gives the `source_term`, `target_term`, and the spans in `target` where the target term was applied. ## Span ranges @@ -50,67 +52,44 @@ A target span of `{ "start": 20, "end": 29 }` covers `target[20:29]`, the 9 code - `source_spans` and `target_spans` are always present on an issue. If no span applies to that side, the value is an empty array - Within a single issue, the ranges in `source_spans` (and in `target_spans`) are sorted by `start` and do not overlap - Different issues may cover the same part of a segment -- `ranges` on a glossary entry follows the same convention and indexes into `target` +- `ranges` on an applied glossary term pair follows the same convention and indexes into `target` ## Severity values -The `severity` field on an issue takes one of four values. +The `severity` field on an issue takes one of three values. | **Value** | **Description** | |---|---| | `Critical` | Renders the content unusable or significantly changes its meaning. For example, the meaning is reversed, important information is missing, or the content is unsuitable for the intended audience. | | `Major` | Misleads the reader or significantly alters the meaning. The general idea is clear, but specific details are wrong, terminology is incorrect, or grammar issues make the text hard to understand. | | `Minor` | Does not make the text unreadable, but can make it harder to understand and less appealing. | -| `Unclear (Check Needed)` | A possible issue that the segment alone does not provide enough context to confirm. | ## Type and sub-type values Every issue carries a `type`, the top-level category, and a `sub_type`, which narrows it within that type. The five types and their sub-types are listed below. - `type`, `sub_type`, and `severity` are open strings on the wire, not closed sets. Match the values below rather than switching exhaustively over them, so an unlisted value does not break your client. + New values for `type`, `sub_type`, and `severity` may be added without warning. -### Accuracy - -| **sub_type** | **Description** | -|---|---| -| `Addition` | The target includes text that was not part of the source. | -| `Omission` | Content from the source is missing from the target. | -| `Mistranslation` | The content from the target doesn't match the content of the source. | -| `Over-translation` | The target is more specific than the source. | -| `Under-translation` | The target is less specific than the source. | -| `Untranslated text` | Content that should have been translated has been left untranslated. | - -### Fluency - -| **sub_type** | **Description** | -|---|---| -| `Punctuation` | Punctuation is used incorrectly. | -| `Spelling` | Incorrect spelling in the target text. | -| `Grammar` | Issues with the grammar or syntax of the text, other than spelling and orthography. | -| `Grammatical register` | The text uses the wrong grammatical register, such as informal forms where formal is required. | -| `Inconsistency` | The text is not internally consistent. For example, using two different abbreviations for the same term. | -| `Character encoding` | Characters are garbled due to incorrect application of an encoding. | - -### Style - -| **sub_type** | **Description** | -|---|---| -| `Awkward` | The text is written in an awkward style. | -| `Inconsistent style` | The text uses inconsistent stylistic conventions across sections. | - -### Miscellaneous - -| **sub_type** | **Description** | -|---|---| -| Not enumerated | An error that does not fall into the other categories but is nonetheless clearly identifiable as a mistake. The sub-types of this type are not a fixed set, so read `sub_type` as free text. | - -### InternalTQEError - -| **sub_type** | **Description** | -|---|---| -| `SegmentTooLarge` | The segment's source and target exceed 10,000 characters combined, so it was not analyzed. Reported with severity `Critical`. | +| **type** | **sub_type** | **Description** | +|---|---|---| +| `Accuracy` | `Addition` | The target includes text that was not part of the source. | +| `Accuracy` | `Omission` | Content from the source is missing from the target. | +| `Accuracy` | `Mistranslation` | The content from the target doesn't match the content of the source. | +| `Accuracy` | `Over-translation` | The target is more specific than the source. | +| `Accuracy` | `Under-translation` | The target is less specific than the source. | +| `Accuracy` | `Untranslated text` | Content that should have been translated has been left untranslated. | +| `Fluency` | `Punctuation` | Punctuation is used incorrectly. | +| `Fluency` | `Spelling` | Incorrect spelling in the target text. | +| `Fluency` | `Grammar` | Issues with the grammar or syntax of the text, other than spelling and orthography. | +| `Fluency` | `Grammatical register` | The text uses the wrong grammatical register, such as informal forms where formal is required. | +| `Fluency` | `Inconsistency` | The text is not internally consistent. For example, using two different abbreviations for the same term. | +| `Fluency` | `Character encoding` | Characters are garbled due to incorrect application of an encoding. | +| `Style` | `Awkward` | The text is written in an awkward style. | +| `Style` | `Inconsistent style` | The text uses inconsistent stylistic conventions across sections. | +| `Miscellaneous` | Not enumerated | An error that does not fall into the other categories but is nonetheless clearly identifiable as a mistake. The sub-types of this type are not a fixed set, so read `sub_type` as free text. | +| `InternalTQEError` | `SegmentTooLarge` | The segment's source and target exceed 10,000 characters combined, so it was not analyzed. Reported with severity `Critical`. | An issue of this type reports that a segment could not be evaluated rather than a defect in the translation. The rest of the document is evaluated normally. diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 0c041752..015c4c86 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -85,9 +85,15 @@ A quality evaluation is a report on the translation DeepL just produced: for eac Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select customers only. To have it enabled for your account, contact your customer success manager; until then, opting in returns HTTP 403. -Add [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document) to the upload. Two limits apply, and both are checked before the upload is accepted: only `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 files can be evaluated, and quality evaluation covers fewer language pairs than translation does. Check the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) before you opt in. +To request a quality evaluation, set [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document) to `true` when uploading a document. -An ineligible file type or an unsupported language pair is rejected with HTTP 400 before the translation starts, so nothing is translated and nothing is billed. Opting in never puts the translation itself at risk. +When `enable_quality_evaluation=true`, three additional checks run before the translation request is accepted: + +- The language pair must be in the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs). Quality evaluation supports fewer language pairs than document translation. +- The file must be `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, or XLIFF 2.1. Quality evaluation supports fewer file types than document translation. +- Your account must have enough quality evaluation characters. Quality evaluation characters are metered separately from translation characters. + +If any check fails, the request is rejected before translation starts, so nothing is translated or billed. Opting in never puts the translation itself at risk. ```bash curl -X POST https://api.deepl.com/v2/document \ @@ -126,8 +132,16 @@ A finished evaluation returns HTTP 200 whether it succeeded or failed, so branch "segments": [ { "segment_index": 0, + "segment_score": 38.5, "source": "Our Q3 revenue came in 5% above forecast.", "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.", + "applied_glossary_term_pairs": [ + { + "source_term": "forecast", + "target_term": "Prognose", + "ranges": [{ "start": 34, "end": 42 }] + } + ], "errors": [ { "type": "Accuracy", @@ -143,7 +157,7 @@ A finished evaluation returns HTTP 200 whether it succeeded or failed, so branch } ``` -Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluation/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the glossary entries a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluation/poll). +Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluation/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the applied glossary term pairs a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluation/poll). ### Document format conversions By default, the translated document comes back in the same format as the input. Two conversions differ: diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 69631417..b2e72833 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -12,7 +12,7 @@ rss: true ## September 20 - Quality Evaluation for Document Translation (Beta) - A **quality evaluation** is a report on a translation DeepL has produced: for each segment it lists detected issues such as mistranslations, omissions, and fluency or style problems, with a severity and the character range the issue applies to. Use it to target human review at the segments that need it. - Request one by setting `enable_quality_evaluation=true` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). The upload response then returns a `quality_evaluation_job_id`, which you poll at [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) to retrieve the report. See [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation) for the full flow. -- Reports cover `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and a subset of the language pairs translation supports. Each report also returns the source and translated text of every segment, plus the glossary entries that were applied to it. +- Reports cover `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and a subset of the language pairs translation supports. Each report also returns a quality score, the source and translated text, and any applied glossary term pairs for every segment. - In beta and available to select customers only. To have it enabled for your account, contact your customer success manager. ## September 11 - Speaker Match Voice for the Voice API From c9640d5587ea151ca5a45f347ef98a4fa7b305e9 Mon Sep 17 00:00:00 2001 From: Thomas Neil Date: Wed, 23 Sep 2026 15:06:15 +0300 Subject: [PATCH 3/3] docs: pluralize quality-evaluations docs path to match the API The poll page now lives at /api-reference/quality-evaluations/poll, matching GET /v1/quality-evaluations/{job_id}. Singular docs URLs redirect, and the file-translation how-to links the Help Center overview. Co-authored-by: Cursor --- api-reference/openapi.json | 24 ++++++++--------- api-reference/openapi.yaml | 26 +++++++++---------- .../poll.mdx | 0 docs.json | 18 ++++++++++--- docs/best-practices/document-translations.mdx | 6 ++--- docs/resources/roadmap-and-release-notes.mdx | 2 +- 6 files changed, 44 insertions(+), 32 deletions(-) rename api-reference/{quality-evaluation => quality-evaluations}/poll.mdx (100%) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 1076c8dc..2e75f26f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -1216,7 +1216,7 @@ "default": false }, "enable_quality_evaluation": { - "description": "(beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) with it for a per-segment report of translation issues. The translation itself is unaffected.\n\n**Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) only.\n\nRejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`.", + "description": "(beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) with it for a per-segment report of translation issues. The translation itself is unaffected.\n\n**Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs) only.\n\nRejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`.", "type": "boolean", "default": false }, @@ -1255,7 +1255,7 @@ "example": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" }, "quality_evaluation_job_id": { - "description": "(beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll).", + "description": "(beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll).", "type": "string", "example": "04DE5AD98A02647D83285A36021911C6" } @@ -6697,7 +6697,7 @@ } }, "404": { - "description": "No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluation/poll#report-retention).", + "description": "No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluations/poll#report-retention).", "content": { "application/json": { "schema": { @@ -10993,12 +10993,12 @@ }, "source": { "type": "string", - "description": "The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", + "description": "The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text).", "example": "Our Q3 revenue came in 5% above forecast." }, "target": { "type": "string", - "description": "The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text).", + "description": "The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text).", "example": "Unser Q3-Umsatz lag 5 % unter der Prognose." }, "applied_glossary_term_pairs": { @@ -11038,7 +11038,7 @@ }, "ranges": { "type": "array", - "description": "Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", + "description": "Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges).", "items": { "$ref": "#/components/schemas/QualityEvaluationSpan" } @@ -11058,7 +11058,7 @@ "properties": { "type": { "type": "string", - "description": "Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values).", + "description": "Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values).", "enum": [ "Accuracy", "Fluency", @@ -11070,7 +11070,7 @@ }, "sub_type": { "type": "string", - "description": "Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values).", + "description": "Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values).", "enum": [ "Addition", "Omission", @@ -11092,7 +11092,7 @@ }, "severity": { "type": "string", - "description": "How serious the issue is. See [Severity values](/api-reference/quality-evaluation/poll#severity-values).", + "description": "How serious the issue is. See [Severity values](/api-reference/quality-evaluations/poll#severity-values).", "enum": [ "Critical", "Major", @@ -11107,14 +11107,14 @@ }, "source_spans": { "type": "array", - "description": "Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", + "description": "Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges).", "items": { "$ref": "#/components/schemas/QualityEvaluationSpan" } }, "target_spans": { "type": "array", - "description": "Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", + "description": "Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges).", "items": { "$ref": "#/components/schemas/QualityEvaluationSpan" } @@ -11127,7 +11127,7 @@ "start", "end" ], - "description": "A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges).", + "description": "A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges).", "properties": { "start": { "type": "integer", diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index ecb498c2..c096f648 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -995,9 +995,9 @@ paths: default: false enable_quality_evaluation: description: |- - (beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) with it for a per-segment report of translation issues. The translation itself is unaffected. + (beta) When `true`, DeepL also evaluates the finished translation and returns a `quality_evaluation_job_id`. Poll [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) with it for a per-segment report of translation issues. The translation itself is unaffected. - **Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs) only. + **Important:** Available to select customers; contact your customer success manager to enable it. Supported for `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and for the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs) only. Rejected before the upload is accepted: `403` if quality evaluation is not enabled for the account, `400` for an ineligible file type, an unsupported language pair, or a value other than `true` or `false`. type: boolean @@ -1039,7 +1039,7 @@ paths: example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A quality_evaluation_job_id: description: |- - (beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll). + (beta) A unique ID assigned to the quality evaluation. Returned only when the request set `enable_quality_evaluation=true`. Use it to retrieve the report from [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll). type: string example: 04DE5AD98A02647D83285A36021911C6 example: @@ -4728,7 +4728,7 @@ paths: message: job_id must be a valid UUID. '404': description: |- - No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluation/poll#report-retention). + No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluations/poll#report-retention). content: application/json: schema: @@ -8314,11 +8314,11 @@ components: example: 38.5 source: type: string - description: The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). + description: The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text). example: Our Q3 revenue came in 5% above forecast. target: type: string - description: The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluation/poll#segment-text). + description: The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text). example: Unser Q3-Umsatz lag 5 % unter der Prognose. applied_glossary_term_pairs: type: array @@ -8348,7 +8348,7 @@ components: example: Prognose ranges: type: array - description: Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). + description: Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationIssue: @@ -8363,7 +8363,7 @@ components: properties: type: type: string - description: Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values). + description: Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values). enum: - Accuracy - Fluency @@ -8373,7 +8373,7 @@ components: example: Accuracy sub_type: type: string - description: Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluation/poll#type-and-sub-type-values). + description: Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values). enum: - Addition - Omission @@ -8393,7 +8393,7 @@ components: example: Mistranslation severity: type: string - description: How serious the issue is. See [Severity values](/api-reference/quality-evaluation/poll#severity-values). + description: How serious the issue is. See [Severity values](/api-reference/quality-evaluations/poll#severity-values). enum: - Critical - Major @@ -8405,12 +8405,12 @@ components: example: "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications." source_spans: type: array - description: Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). + description: Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' target_spans: type: array - description: Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). + description: Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationSpan: @@ -8418,7 +8418,7 @@ components: required: - start - end - description: A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluation/poll#span-ranges). + description: A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). properties: start: type: integer diff --git a/api-reference/quality-evaluation/poll.mdx b/api-reference/quality-evaluations/poll.mdx similarity index 100% rename from api-reference/quality-evaluation/poll.mdx rename to api-reference/quality-evaluations/poll.mdx diff --git a/docs.json b/docs.json index 5df27eaf..77c2be4a 100644 --- a/docs.json +++ b/docs.json @@ -235,7 +235,7 @@ "group": "Quality Evaluation", "tag": "BETA", "pages": [ - "api-reference/quality-evaluation/poll" + "api-reference/quality-evaluations/poll" ], "drilldown": false }, @@ -622,13 +622,25 @@ "source": "/api-reference/document", "destination": "/api-reference/document/upload-and-translate-a-document" }, + { + "source": "/api-reference/quality-evaluations", + "destination": "/api-reference/quality-evaluations/poll" + }, + { + "source": "/api-reference/quality-evaluations/submit", + "destination": "/api-reference/quality-evaluations/poll" + }, { "source": "/api-reference/quality-evaluation", - "destination": "/api-reference/quality-evaluation/poll" + "destination": "/api-reference/quality-evaluations/poll" + }, + { + "source": "/api-reference/quality-evaluation/poll", + "destination": "/api-reference/quality-evaluations/poll" }, { "source": "/api-reference/quality-evaluation/submit", - "destination": "/api-reference/quality-evaluation/poll" + "destination": "/api-reference/quality-evaluations/poll" }, { "source": "/api-reference/multilingual-glossaries", diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 015c4c86..0469dd32 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -79,7 +79,7 @@ Translation time depends on document size and server load: small documents typic You can apply a glossary to a document translation with the `glossary_id` parameter (or up to 5 glossaries with `glossary_ids`). This requires the `source_lang` parameter to be set, and the glossary's language pair has to match the language pair of the request. ### Requesting a quality evaluation -A quality evaluation is a report on the translation DeepL just produced: for each segment of the document it lists the issues it detected, such as mistranslations, omissions, and fluency or style problems, with a severity and the character range each issue applies to. Use it to target human review at the segments that need it instead of reviewing the whole document. +A quality evaluation is a report on the translation DeepL just produced: for each segment of the document it lists the issues it detected, such as mistranslations, omissions, and fluency or style problems, with a severity and the character range each issue applies to. Use it to target human review at the segments that need it instead of reviewing the whole document. For a product overview, see [About quality evaluation for file translations](https://support.deepl.com/hc/en-us/articles/26360433777436-About-quality-evaluation-for-file-translations). Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select customers only. To have it enabled for your account, contact your customer success manager; until then, opting in returns HTTP 403. @@ -89,7 +89,7 @@ To request a quality evaluation, set [`enable_quality_evaluation`](/api-referenc When `enable_quality_evaluation=true`, three additional checks run before the translation request is accepted: -- The language pair must be in the [supported language pairs](/api-reference/quality-evaluation/poll#supported-language-pairs). Quality evaluation supports fewer language pairs than document translation. +- The language pair must be in the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs). Quality evaluation supports fewer language pairs than document translation. - The file must be `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, or XLIFF 2.1. Quality evaluation supports fewer file types than document translation. - Your account must have enough quality evaluation characters. Quality evaluation characters are metered separately from translation characters. @@ -157,7 +157,7 @@ A finished evaluation returns HTTP 200 whether it succeeded or failed, so branch } ``` -Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluation/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the applied glossary term pairs a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluation/poll). +Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluations/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the applied glossary term pairs a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluations/poll). ### Document format conversions By default, the translated document comes back in the same format as the input. Two conversions differ: diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 3a8dd11a..c8f7b0cb 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -21,7 +21,7 @@ rss: true ## September 20 - Quality Evaluation for Document Translation (Beta) - A **quality evaluation** is a report on a translation DeepL has produced: for each segment it lists detected issues such as mistranslations, omissions, and fluency or style problems, with a severity and the character range the issue applies to. Use it to target human review at the segments that need it. -- Request one by setting `enable_quality_evaluation=true` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). The upload response then returns a `quality_evaluation_job_id`, which you poll at [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluation/poll) to retrieve the report. See [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation) for the full flow. +- Request one by setting `enable_quality_evaluation=true` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). The upload response then returns a `quality_evaluation_job_id`, which you poll at [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) to retrieve the report. See [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation) for the full flow. - Reports cover `docx`, `pptx`, `pdf`, `srt`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and a subset of the language pairs translation supports. Each report also returns a quality score, the source and translated text, and any applied glossary term pairs for every segment. - In beta and available to select customers only. To have it enabled for your account, contact your customer success manager.