TrueIdiom

Supported file formats

TrueIdiom takes files on two different paths. A PDF, Word or Excel file is translated in place — layout, pagination, tables and styling preserved, only the text replaced — and comes back in the format you sent. Everything else is flattened to text, translated as text, and returned as a golden translation rather than as a rebuilt file.

Layout-preserving document translation

These formats go through the document pipeline at POST /api/documents/translate, and come back as the same kind of file with the layout intact.

Format Extension Content type
PDF .pdf application/pdf
application/x-pdf
Word .docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel .xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Uploading one of these to the text endpoint (POST /api/translations, as multipart/form-data with a source_document part) routes into this same pipeline and returns a document job in the same shape. You do not have to pick the right endpoint by hand — but you do have to poll and download it as a document job.

Caution: Layout-preserving document translation is not covered by the free trial. Your first document needs a subscription; start with text if you are still trialling.

What each format keeps

In-place translation replaces text and leaves the rest of the file as it was. What counts as translatable text differs by format:

Format Translated Kept as it was
PDF Text on the visible page. Text outside the page’s visible area is neither translated nor billed. Page count, page size and images; bookmarks, page labels, links and fillable form fields — except an XFA form, and the form fields of a signed document, whose signature cannot cover a translation. A translation too long for its space is set smaller and, if it still does not fit, cut short; the job’s quality report flags every cut, and any heavy shrinking.
Word The body, tables included, and the headers and footers. Styles, images, numbering, and page and column breaks. Hyperlinks keep their targets (the quality report flags one placed approximately or left empty). Page numbers, dates and the other fields Word computes itself keep their live values. Not translated: footnotes, endnotes, comments, text boxes, content controls and tracked changes. Formatting that changes inside a paragraph takes the paragraph’s main formatting. Arabic, Persian and Urdu targets are set right to left.
Excel Text in cells. Formulas, numbers, dates, cell styles, charts, images, pivot tables and macros. Not translated: sheet names, text inside formulas, literal dropdown lists, cells with no letters in them, and the column headers of an Excel Table, which stay in the source language so formulas that name the columns keep working (the quality report says how many were kept). Formatting that changes inside one cell comes back as plain text in the cell’s style.

Text uploads on the translation endpoint

POST /api/translations also accepts a file whose text it extracts and translates as text. The upload is accepted when its extension is one of these, when its declared content type is one of these, or when the declared content type starts with text/.

Accepted extensions Accepted content types
.csv .docx .htm .html .json .md .pdf .txt .xml application/json
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/xml
text/csv
text/html
text/markdown
text/plain
text/xml
any text/*

An upload outside that set is refused with 415 unsupported source_document type. Text files must be UTF-8 (with or without a byte-order mark) or UTF-16 with a byte-order mark; any other encoding is refused with 400 and nothing is translated. A file whose text extracts to nothing is a 400 too — an empty extraction is a failed read, not an empty translation.

Note: .pdf and .docx appear in both tables, and for a multipart upload the layout path wins. To get plain extracted text out of a PDF or a Word file rather than a rebuilt document, send the file as the raw request body instead, or send the text itself in source_text. A file that cannot be read — corrupt, password-protected, or not really a PDF or Word file — is refused with 400 when it is flattened to text; on the layout path its job fails at the extract stage instead (400 with wait=true).

How a file is recognised

The extension wins over the declared content type. Browsers and HTTP clients routinely send a generic type for Office files (application/octet-stream is the usual culprit), while the extension is what you actually named the document. So detection reads the file name first, and only falls back to the content type when the name carries no recognised extension.

When detection succeeds on content type alone, the matching extension is appended to the stored file name, so the file that comes back is named sensibly.

Upload size limit

Any request body — uploads included — is capped at 30 MB (30,000,000 bytes) on this deployment. The ceiling is checked against the declared length before the body is read, and again against the streamed bytes, so an undeclared or chunked body cannot slip past it. Exceeding it returns 413; nothing is parsed and nothing is billed.

A PDF, Word or Excel file is held to that ceiling on either endpoint. The text endpoint applies a tighter ceiling to the declared size of the text it receives — JSON and raw bodies, and text files uploaded as a form — and source text has a character limit of its own. Both are on Limits & quotas. Word and Excel files are also bounded by what they unpack to and by how much text they hold — see Documents.

What you get back

Documents. GET /api/documents/{document_id}/download streams the translated file. Its Content-Type is the artifact's own — application/pdf, or the Word or Excel content type for Office sources — and the Content-Disposition file name is the source file name, not a translated-suffixed one, so rename on the way out if you need contract.fr.pdf. A name outside ASCII arrives as an ASCII stand-in in filename plus the exact name in filename* (RFC 6266). In the workspace, translated documents are downloaded from the Documents pane in their original format, layout intact.

  • Download as soon as the job's status is translated, and again after every review re-render — each re-render appends a new artifact and the download serves the newest.
  • A job that never reached translated returns 409: document translation is still in progress while it runs, and document translation failed; no translated output is available once it has failed. The source file is never handed back in place of a translation.
  • The stored SHA-256 is re-verified against the bytes before they are served. A mismatch fails with 500 rather than serving suspect content.

Text jobs. Approving a text job publishes it as a golden record. From the job page you can download it as DOCX or PDF in one click, and the same endpoint serves plain text for scripting.

Glossary and translation-memory files

Terminology and translation memory are uploaded as files too, with their own format rules.

Upload Accepted files Rejected with
Terminology (POST /api/terminology) .csv or .tmx (TMX 1.4b) 415 terminology_file must be a .csv or .tmx file for any other suffix; 415 terminology_file must be text/csv or ... must be XML (TMX 1.4b) when the declared content type contradicts the detected kind.
Translation memory (POST /api/tm) .tmx only (TMX 1.4b) 415 tmx_file must be a .tmx file for any other suffix; 415 tmx_file must be XML (TMX 1.4b) when the content type does not match.

The filename suffix decides the kind here as well. With no suffix at all, an XML content type (or a generic application/octet-stream) is treated as TMX and anything else as CSV — and the declared content type must then agree with that reading. A content type’s parameters, such as ; charset=utf-8, are ignored. A glossary CSV must be UTF-8 (with or without a byte-order mark) or UTF-16 with a byte-order mark; any other encoding is refused with 400. Exports come back as TMX 1.4b, so a memory you build here is a memory you can take elsewhere.

source_lang and target_lang are required for a TMX terminology upload and optional for a CSV one. Per-pair capacity limits for both are on Limits & quotas.

What's next