Batch Translation

The TextReveal® HTTP API exposes an endpoint named documents/translate/batch that can translate multiple document's text and/or title into the desired language.

This route allow its users to translate all documents except the text of premium ones. For premium news, users still can translate the title.

Usage

The translation will be faster if the extracted date is provided.

BODY

{
  "documents": [
    {
      "id": "c34ac671a1b0b80078f9acd7e80217e28e8c554e14e1de707fb4370e52299add",
      "extracted": "2022-12-30T22:59:57.502Z"
    },
    {
      "id": "1454343030016",
      "extracted": "2022-12-31T23:59:47.000Z"
    }
  ],
  "fields": [
    "title",
    "text"
  ],
  "language": "french"
}

name	type	description
`documents`	List[Document]	List of documents to translate Required Maximum `25` documents
`documents` > `id`	string	The document id, it can be found in TextReveal® Dashboards. Required Max length `64`
`documents` > `extracted`	date	Extraction date of the document. Using ISO 8601 format. If absent the most recent document will be used.
`fields`	List[string]	Fields to translate. Accepted values: `title`, `text` Default: `["title", "text"]`
`language`	string	The language in which you want the document to be translated. Has to be one of the supported languages. Default: `english`

Response

RESPONSE

[
  {
    "id": "c34ac671a1b0b80078f9acd7e80217e28e8c554e14e1de707fb4370e52299add",
    "extracted": "2022-12-30T22:59:57.502Z",
    "title": "title translated in french",
    "text": "..."
  },
  {
    "error": {
      "statusCode": 403,
      "message": "Forbidden – Access to the data is denied",
      "field": {
        "text": {
          "statusCode": 403,
          "message": "The download of licensed text is not allowed."
        }
      }
    },
    "id": "1454343030016",
    "extracted": "2022-12-31T23:59:47.000Z",
    "title": "title translated in french"
  }
]

The response is not guaranteed to be in the same order as the input.

Error handling

We raise error an error in the following cases:

The user’s company is out of quota:
- Each company can translate up to 10.000 documents. This quota is defined in the company license.
- Each document count as 1 translation.
- We return a 403 error with all information in headers in this case.
A document is not found or his language is not supported:
- This document is still counted in the quota.
- Other documents are not impacted.
An error occurred when translating a field:
- Other fields are not impacted.
- An error containing helpful information is added in the document response.

RESPONSE

[
  {
    "id": "97563b96-eeb7-492f-b12c-fbfa03927d6d",
    "extracted": "2023-01-13T14:51:57.740Z",
    "error": {
      "message": "Document 97563b96-eeb7-492f-b12c-fbfa03927d6d not found on date 2023-01-13T14:51:57.740Z",
      "statusCode": 404
    }
  },
  {
    "id": "6ab99392-b8cb-4533-9c28-01718a2360fe",
    "extracted": "2023-06-27T13:49:14.740Z",
    "text": "the document's text translated",
    "error": {
      "field": {
        "title": {
          "message": "Failed to translate title",
          "statusCode": 500
        }
      }
    }
  }
]

Partial translation

When a document's text or title reaches a length of 10,000 bytes, only the first 10,000 bytes are translated.

This limit is lowered depending on the content of the document, to avoid sentence breaks.
If a sentence reaches the 10,000 bytes limit, it is ignored.
If there is no sentence with less than 10.000 bytes, an error is thrown.

When a partial translation is done, the returned document will contain "partial": true