This article is part of the "KolmoPDF: Product Guides & Updates" series. For a full map of parsing, translation, and API capabilities, read the series overview.
Plain document translators handle single-column letters well, then fall apart on technical PDFs. A scanned specification sheet has no text layer, so text-based tools return blank pages or blocks of broken characters. A two-column paper reflows into a single stream, detaching figure captions from their charts and scrambling table cells. Inline equations fare worst of all: variables like $d_k$, subscripts, and operator names get translated literally or dropped into missing-glyph boxes.
Automation introduces a second trap. Requesting both a translated PDF and a bilingual side-by-side PDF in a single API call causes the server to bundle both files into a ZIP archive. Writing those response bytes straight to output.pdf produces a file that every PDF viewer flags as damaged.
Choosing between layout PDFs and translated Markdown
KolmoPDF exposes two distinct translation paths that share the same account credit balance and the same 300 MB / 800-page file limits:
-
PDF Translation (
POST /api/v1/jobs/translate-pdf) costs 2 credits per page across any pair of 9 supported languages (English, Simplified Chinese, Japanese, Korean, French, German, Spanish, Russian, and Portuguese). It rebuilds the document as a translated PDF, a bilingual PDF, or a ZIP containing both. Use this path when engineers, patent reviewers, or study groups need to read translated pages alongside the original tables, figures, and pagination. -
PDF to Markdown (
POST /api/v1/jobs/parsewithenable_translation=true) costs 3 credits per page (compared to 2 credits per page without translation). It outputs Markdown with GitHub-flavored pipe tables and LaTeX math blocks, controlled byoutput_options(original,translated, orbilingual). Use this path when the text is going into Obsidian, Notion, or a RAG ingestion pipeline.
New accounts start with 300 free credits on signup plus 50 daily check-in credits, and one-time Pay-As-You-Go packs run $3 per 1,000 credits without a subscription. Both paths accept native digital PDFs and scanned page stacks directly. Because the underlying Visual Language Model treats each page as image regions, scanned PDFs do not require an Adobe Acrobat OCR pass beforehand.
What survives in a real two-column paper
On the public Attention Is All You Need showcase, KolmoPDF processes the 15-page arXiv:1706.03762v7 paper (Vaswani et al., 2017). Comparing the parsed English Markdown with the bilingual Markdown output shows how mathematical tokens and section structure behave during translation.
In Section 3.1, the original English paragraph reads:
Encoder: The encoder is composed of a stack of $N = 6$ identical layers. Each layer has two sub-layers. The first is a multi-head self-attention mechanism, and the second is a simple, position-wise fully connected feed-forward network. We employ a residual connection [11] around each of the two sub-layers, followed by layer normalization [1]. That is, the output of each sub-layer is $\text{LayerNorm}(x + \text{Sublayer}(x))$, where $\text{Sublayer}(x)$ is the function implemented by the sub-layer itself. To facilitate these residual connections, all sub-layers in the model, as well as the embedding layers, produce outputs of dimension $d_{\text{model}} = 512$.
In the bilingual output, the Chinese translation preserves every math token, citation number, and LaTeX expression intact inside the translated sentence:
编码器: 编码器由 $N = 6$ 个相同层的堆叠组成。每个层包含两个子层。第一个是多头自注意力机制,第二个是简单的逐位置全连接前馈网络。我们在每个子层周围使用残差连接 [11],随后进行层归一化 [1]。也就是说,每个子层的输出是 $\text{LayerNorm}(x + \text{Sublayer}(x))$,其中 $\text{Sublayer}(x)$ 是由子层自身实现的功能。为了促进这些残差连接,模型中的所有子层以及嵌入层都生成维度为 $d_{\text{model}} = 512$ 的输出。
Display equations such as Scaled Dot-Product Attention (\text{Attention}(Q, K, V) = \text{softmax}(\frac{QK^T}{\sqrt{d_k}})V) and figure captions (Figure 1 / 图1) stay aligned to their surrounding prose rather than getting stripped or reflowed across columns.
By default, text inside embedded raster figures and tables stays untouched unless you opt in. On the web form and in the API, enable_table_translation translates text inside tables and enable_image_translation translates text inside charts and diagrams. Both options increase processing time per page, so leave them off when table headers or chart labels are standard symbols you want left in the source language.
Locking domain terminology with a CSV glossary
Technical manuals and datasheets often fail on consistency rather than grammar. A product codename or medical term translated one way on page 2 and another way on page 19 creates confusion during review.
Both the web translator and POST /api/v1/jobs/translate-pdf accept a UTF-8 CSV glossary file (up to 2 MB). The header row uses standard two-letter language codes from the 9 supported languages (en,zh,ja,ko,fr,de,es,ru,pt), and each row pairs the source term with your preferred translation:
en,zh
LayerNorm,LayerNorm
Multi-Head Attention,多头注意力机制
Scaled Dot-Product Attention,缩放点积注意力
Uploading that CSV keeps brand identifiers, untranslated symbol names, and domain vocabulary fixed across the entire document.
Calling translate-pdf safely from Python
All endpoints live under the base URL https://www.kolmopdf.com and authenticate via Authorization: Bearer <KOLMOPDF_API_KEY>. You can generate a key from API Management on any plan, including Free.
Jobs run asynchronously. Creating a job returns HTTP 202 Accepted with a job_... ID and links.self. Passing a unique Idempotency-Key header per submission guarantees that network retries do not double-charge credits. Each API key supports up to 3 concurrent running jobs, and finished result files remain downloadable for 7 days.
The critical client-side rule is never to assume the download extension. When layoutModes has a single mode (translated_only or side_by_side), result.kind is usually pdf. When both modes are requested, result.kind is zip. Always read result.filename and result.kind from the succeeded job payload before writing to disk:
import os
import time
import uuid
from pathlib import Path
import requests
BASE_URL = "https://www.kolmopdf.com"
API_KEY = os.environ.get("KOLMOPDF_API_KEY")
if not API_KEY:
raise RuntimeError("Set KOLMOPDF_API_KEY in your environment first.")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def translate_pdf(
pdf_path: str,
source_lang: str = "en",
target_lang: str = "zh",
layout_modes: str = "translated_only,side_by_side",
glossary_path: str | None = None,
translate_tables: bool = True,
translate_images: bool = False,
) -> Path:
files = {"file": open(pdf_path, "rb")}
if glossary_path:
files["glossary"] = open(glossary_path, "rb")
data = {
"sourceLanguage": source_lang,
"targetLanguage": target_lang,
"layoutModes": layout_modes,
"enable_table_translation": str(translate_tables).lower(),
"enable_image_translation": str(translate_images).lower(),
}
create_headers = {
**HEADERS,
"Idempotency-Key": str(uuid.uuid4()),
}
try:
resp = requests.post(
f"{BASE_URL}/api/v1/jobs/translate-pdf",
headers=create_headers,
files=files,
data=data,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
finally:
for fh in files.values():
fh.close()
job_url = f"{BASE_URL}{job['links']['self']}"
print(f"Created job {job['id']} ({job['points_deducted']} credits deducted)")
while job["status"] in ("queued", "processing"):
time.sleep(3)
poll = requests.get(job_url, headers=HEADERS, timeout=30)
poll.raise_for_status()
job = poll.json()
if job["status"] != "succeeded":
err = (job.get("error") or {}).get("message", job["status"])
raise RuntimeError(f"Job {job['id']} failed: {err}")
result = job["result"]
out_name = Path(result["filename"]).name
download_url = f"{BASE_URL}{result['download_url']}"
dl = requests.get(download_url, headers=HEADERS, timeout=120)
dl.raise_for_status()
# Guard against saving a ZIP bundle under a .pdf name
if result["kind"] == "zip" and not out_name.lower().endswith(".zip"):
out_name = f"{Path(out_name).stem}.zip"
out_path = Path(out_name)
out_path.write_bytes(dl.content)
print(f"Saved {out_path} (kind={result['kind']}, bytes={len(dl.content)})")
return out_path
if __name__ == "__main__":
translate_pdf("paper.pdf", glossary_path="glossary.csv")
For interactive terminal or coding-agent workflows, you can skip writing boilerplate by installing the standalone agent skill (npx skills add komoai2026/kolmopdf-skill), which wraps the same Jobs API endpoints and ZIP handling via Node.js 20+. For long CLI jobs, the API also provides a Server-Sent Events stream at GET /api/v1/jobs/{id}/events so clients do not have to poll.
Verification boundaries before citing or batching
Layout translation preserves surrounding typography and restores LaTeX formulas, yet dense scanned equations can still misread a tiny index such as d_k vs d_v. Check subscripts, superscripts, and equation numbers against the source PDF before citing numbers or reusing a translated passage.
Turning on enable_image_translation and enable_table_translation also slows down per-page turnaround, so benchmark runtime and visual alignment on 5 to 10 representative pages before submitting an 800-page manual.
Finally, standard processing runs online over TLS and does not use uploaded PDFs or translations to train AI models, as stated in the privacy policy. If compliance rules prohibit sending confidential internal records to external endpoints, keep those documents local.
To try a paper in the browser or generate an API key, open KolmoPDF PDF Translation and the API Guide.
Top comments (0)