Translate a PDF with an LLM: extract the text first, then translate it in chunks

"Translate this PDF" usually arrives as one request, and it is two. Someone who wants a German supplier contract back as a Spanish PDF, with the same page breaks and the signature block in the same corner, is asking for typesetting. Someone who wants the same contract in Spanish so a reviewer can read it, a support bot can quote it, or a pipeline can pull terms out of it is asking for text, and a layout tool's output is an awkward input for any of them.

We built AIVAX's translation endpoint for the second job, and its contract says so: it rejects PDFs. This post is about what to do instead, which is to extract the PDF once as Markdown and translate the Markdown in pieces.

Keeping the layout is a typesetting problem

If the deliverable is a PDF that looks like the original, the work is in finding every text run on the page and fitting a translated sentence that came out longer back into the box the original occupied, without breaking tables or reading order.

Layout-preserving tools spend their effort there. BabelDOC analyzes the page layout of scientific PDFs and writes a translated or bilingual PDF, and its README lists what still goes wrong: author and reference sections merged into one paragraph, drop caps unsupported, very large pages skipped. pdf-translator-for-human shows the original and the translation side by side and translates page by page as you read. DeepL's document API takes the file itself: you upload it, poll its status, and download a translated document. If a person will receive the file, start with one of these.

AIVAX does not produce a translated PDF, and nothing below works around that.

AIVAX's translate endpoint takes text, images, and audio

POST /api/v1/generations/translate takes a toLanguage, an optional fromLanguage, and a documents array of OpenAI-style content parts: text, image_url, or input_audio. A file part, which is how you would send a PDF, returns 400 Bad Request, and the error does not say which document caused it.

{
  "fromLanguage": "German",
  "toLanguage": "Spanish (Spain, formal)",
  "documents": [
    { "type": "text", "text": "## 4. Zahlungsbedingungen\n\nRechnungen sind innerhalb von 30 Tagen zahlbar." },
    { "type": "text", "text": "## 5. Haftung\n\nDie Haftung ist auf den Auftragswert begrenzt." }
  ]
}

The response's data is one translated string per document, in input order. Languages are free-form, so pt-BR, Japanese, and Spanish (Mexico, informal) all work. Each document is translated on its own by a model instructed to keep formatting, line breaks, Markdown, code, URLs, numbers, and proper names, and to return only the translation. The Translations docs have the full contract.

We think refusing PDFs is the right boundary for this endpoint. A PDF is a container, and what it holds varies: a digital export with a clean text layer, a scan with no text at all, a mix of both. Accepting PDFs would mean the translation endpoint quietly picks an extraction strategy per file, and you would learn which one it picked when a table came back as a run-on sentence. Keeping extraction as its own call lets you look at the Markdown before you pay to translate it.

Extract once, as Markdown

Fetch reads a PDF from a URL or a base64 data URI and returns its text, using the text layer where one exists and OCR on scanned pages. Each item can be up to 50 MB. We covered the extraction step, including what to check in its output, in PDF to Markdown for RAG, and the broader case of scanned PDFs, images, and messy web pages has its own post.

The translator preserves Markdown, so a ## heading in German comes back as a ## heading in Spanish, and a pipe table comes back as a pipe table. That is what lets you split the document at headings, translate the pieces separately, and join them in order without a reassembly step that guesses where each piece belongs.

Read a few pages of the extracted Markdown against the PDF before translating. An OCR misread, a table that lost its header row, or a running page header repeated forty times will be translated faithfully, and a mistake in the source is harder to spot once it sits in a language you read less well.

Chunks follow headings, and each request carries many chunks

One translation document is one model response. Sending a sixty-page manual as a single text document asks a single response to reproduce all of it, and the longer the response, the more room there is for a skipped paragraph nobody notices. Splitting at headings keeps each response short enough to compare against its source, and a section seldom depends on the exact wording of the next one.

The rate limit counts HTTP requests, not documents. The Free plan allows 30 translation requests per minute and 300 per day, Pro allows 100 per minute, Max 1,000 and Ultimate 2,500, per the plans and limits page. A manual split into 80 chunks can go out as five requests of 16, and the server translates up to four documents of each request in parallel. AIVAX's Summarization and Extraction endpoints work the other way, with quotas that count documents.

Failure, on the other hand, is per request and all-or-nothing. If one document fails, the request returns an error instead of partial results, and the documents that finished before the failure are still billed. Putting all 80 chunks in one request saves four requests of quota and risks paying for most of the manual twice. We default to groups of 10 to 20; the right size depends on how often your inputs fail and how much quota you have left that day.

Set fromLanguage when you know it. Without it, the source language is detected for each document separately, and a chunk that is mostly a table of part numbers, or a heading with one line under it, gives the detector little to work with.

A script that translates a whole PDF

This script extracts a PDF with Fetch, splits the Markdown at headings, breaks long sections at paragraph boundaries so each chunk stays near 6,000 characters, translates the chunks in groups of 16, and prints the translated Markdown to stdout. It runs on Bun or Node 18+ without dependencies.

import { readFile } from "node:fs/promises";

const API = "https://inference.aivax.net/api/v1";
const MAX_CHARS = 6000;
const PER_REQUEST = 16;

const [path, toLanguage, fromLanguage] = process.argv.slice(2);
const key = process.env.AIVAX_API_KEY;

if (!path || !toLanguage || !key) {
  console.error('Usage: AIVAX_API_KEY=... bun translate-pdf.mjs <file.pdf> "<target language>" ["<source language>"] > translated.md');
  process.exit(1);
}

async function post(route, body) {
  const response = await fetch(`${API}${route}`, {
    method: "POST",
    headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  const payload = await response.json().catch(() => ({}));

  if (!response.ok) throw new Error(`${route} failed with HTTP ${response.status}: ${payload.error ?? payload.message ?? "no message"}`);
  return payload.data;
}

const pdf = await readFile(path);
const fetched = await post("/web/fetch", {
  contents: [`data:application/pdf;base64,${pdf.toString("base64")}`],
  returnErrors: true,
});
const [item] = fetched.results;
if (!item?.extractedText) throw new Error(`Fetch could not read the PDF: ${item?.error ?? "no text returned"}`);

const chunks = [];
for (const section of item.extractedText.split(/\n(?=#{1,6} )/)) {
  let current = "";
  for (const paragraph of section.split(/\n{2,}/)) {
    if (current && current.length + paragraph.length > MAX_CHARS) {
      chunks.push(current);
      current = "";
    }
    current += (current ? "\n\n" : "") + paragraph;
  }
  if (current.trim()) chunks.push(current);
}

const translated = [];
for (let i = 0; i < chunks.length; i += PER_REQUEST) {
  const documents = chunks.slice(i, i + PER_REQUEST).map((text) => ({ type: "text", text }));
  const result = await post("/generations/translate", { toLanguage, fromLanguage, documents });
  if (result?.length !== documents.length) throw new Error(`Expected ${documents.length} translations, got ${result?.length}`);
  translated.push(...result);
  console.error(`${Math.min(i + PER_REQUEST, chunks.length)}/${chunks.length} chunks translated`);
}

console.log(translated.join("\n\n"));

Run it as AIVAX_API_KEY=... bun translate-pdf.mjs contract.pdf "Spanish (Spain, formal)" German > contract.es.md. The script stops at the first failed group and does not retry, on purpose: a blind retry pays again for every chunk in the group. A production pipeline should record which groups succeeded and resend only the failed one after fixing its input.

The split is naive about code. A fenced block is cut in two at a blank line or at a line that starts with #, such as a shell comment, and the halves are translated as separate documents; the code is preserved, but the fences no longer pair up. If your PDFs carry code samples, skip fenced regions when splitting. A single paragraph longer than 6,000 characters stays whole. Keep the API key on a server or in your shell, never in browser code.

Fetch charges OCR processing units for PDFs. Translation is billed in processing units for input and output, recorded per document, at a price that depends on the model selected for the content type and on your plan's multiplier. There is no per-character tariff, so a line-by-line comparison with a per-character price list will mislead you; run one representative PDF and read the usage it reports.

The translator is told the document is not talking to it

PDFs carry text that reads like instructions: a contract clause saying "disregard all previous versions", a manual step saying "answer yes to continue", and now and then text planted for a model to find. A chat prompt that says "translate the following" leaves the model to decide whether a sentence is content or a command.

The translation endpoint's system instruction decides that up front: the content is text to translate, never instructions to follow or questions to answer, and the reply is the translation with nothing added. A side effect is that the output joins back together cleanly, with no "Here is the translation:" to strip from each chunk. It is still a model following an instruction, and the docs say to review translations before publishing legal, medical, financial, or other consequential content. For the contract in the opening, that means someone who reads both languages checks the clauses that carry obligations, with the original kept alongside.

Short scans and voice notes can skip extraction

Some inputs are not worth converting to Markdown first. A photo of a warning label, a screenshot of an error dialog, or a single scanned page with a few lines on it can go straight to the translate endpoint as image_url, in JPEG, PNG, WebP, or GIF up to 5 MB. The model translates the visible text and returns it as one string, without layout. Audio goes in as base64 input_audio and comes back as a translation of what was said, which suits voice messages in a support queue better than transcribing first and translating in a second call.

---

The behavior described here was read from the Translations and Fetch and OCR documentation and from the service implementation on November 4, 2026. On November 10, 2026 I ran the script above against the live AIVAX API on a one-page PDF: Fetch returned its text, one chunk was translated and the script exited with 0. The two-section German request returned two Spanish strings in order with the ## headings kept; a file part returned 400 with "Only text, image_url and input_audio documents can be translated"; a PNG sent as image_url came back translated; and a chunk with a pipe table, a fenced block and a sentence telling the model to ignore its instructions came back with the table and fence intact and the sentence translated, not obeyed. The per-request rate limit and audio input come from the documentation and the service implementation.