Manage your documents
You can use our MT API to get both isolated text and documents translated. In the case of handling documents, there are some restrictions in size, formats and naming, that you should take into account to avoid error responses.
MT API document-related actions
These are the main actions that you can perform when managing your documents with our API:
| Document action | When should I perform this action? |
|---|---|
| Get the list of allowed document formats | Before sending your document for translation so you can check if this is compatible with the MT API allowed formats. |
| Get the list of supported language pairs | Before sending your document for translation so you can check if desired language pair is is supported. |
| Translate document | When your document is ready to be sent for translation. |
| Get document translation information | In case you want to retrieve the status of a document translation (e.g. to check if finished) after you have created it. |
| Download document | When the document is finished, hence fully translated to target language. |
Restrictions
Formats
There is a wide range of allowed formats:
.doc, .docx, .htm, .html, .pdf, .pot, .potx, .pps, .ppt, .pptx, .rtf, .txt, .vsd, .vsdx, .xls, .xlsx, .xlt
(See the full list using our /Get document formats endpoint.)
Translations according to formats
When using different file formats, you should keep in mind that not all elements in the document are translated with our MT API. See in this table which elements are included and excluded from translation.
| Type of format | Included in translation | Excluded from translation | Things to consider |
|---|---|---|---|
| Word files - doc and docx | - All "regular", editable text, including: Headers, Footers,Text boxes,etc. - Index entries. | - Hidden text. -Table of contents. - Index. - Comments. | - Embedded documents and images can cause problems, as can any auto-text fields and other linked in content. - Text boxes might be problematic as well. |
| Excel files - xls and xlsx | - All editable text in regular cells. - Text boxes. - Sheet labels. - Header and footer texts. - Text from charts and text boxes. - Hidden cells, rows, and columns. - Content in locked sheets. | - Hidden worksheets. - Cells containing formulas, including dates. - Comments. - Notes. | Since sheet labels are translated, macros might not work. - Translated sheet label names are cut shorter if they exceed the character limit (31). |
| Visio files - vsdx (.vsd is NOT supported) | "Regular" editable text. | - Locked layers. - Invisible layers. - Non-printable layers. - Screen tips. - Comments. | --- |
| Powerpoint files - ppt and pptx | "Regular" text on slides. | - Text boxes on slides. - Notes. - Hidden slides. - Headers and footers that are not master slides. | - Master slides. - Comments. - Sections. |
| RTF files | Are saved as a .docx file, handled like a .docx file for translation, and are delivered back as an .RTF file, so the same settings as those for .docx files apply. | - Hidden text. - Table of contents. - Index. - Comments. | Same as those for .docx. |
| TXT files | All plain text is translated (as long as it only contains plain text). | --- | --- |
| HTML | All plain text in the file is imported, including drop-down lists, buttons etc. | --- | - The handling works for what you might call “simple” HTML. So all plain text is translated. - Please, do not try to include any .ZIP container as this is not accepted by our MT API, include the HTML file instead. |
Size
- You can only add 1 document per endpoint request.
- Documents are limited to 20MiB.
- Documents are also limited to 50,000 words. If a file exceeds 50,000 words, the tool returns an error message.
Document name
When choosing a name for your to-be-translated document, you should take into consideration some restrictions:
| Restrictions: |
|---|
| ✔️ The name must not exceed 128 characters in length. ✔️ The name can only contain characters from ISO/IEC 8859-1 standard. See the table with the full list of allowed characters here. |
| ❌ Characters that are considered "reserved" or "illegal" by either Windows or Linux, including "Null characters", are not allowed. ❌ Exclude control characters. |
- If you can save a file with a given name on Windows & Unix, then it should be considered valid in our API as well (the only limitation that it has <=128 characters).
Automatically generated file name
If you think that your integration will hit the above mentioned limitations and/or want to provide more loose restrictions for the end-user:
- Your application can submit the document and provide an automatically generated file name (We recommend to use an UUID - universally unique identifier) instead of the real file name.
- Store the real file name in your system and then restore the file name when downloading the translated document.