Hand a customs declaration to a general-purpose translator and you get back a wall of accurate sentences. Hand the same file to the customs officer who has to check it and you get back a rejection, because box 4 is no longer box 4. An official document is not a text that happens to be laid out — it is a form whose meaning lives in which box a value sits in, and whose reader compares it line by line against the original.

This post is about the difference between translating a document and filling one: how template-based translation works, what it costs, where it fails, and — the part most write-ups skip — the two failure modes that only appear once you have been running templates for a while.

A form is not prose that got formatted

Read a birth certificate as text and you get a sequence of labels and values: surname, given name, date of birth, the registry office, a certificate series and number. Read it as a form and you get something stricter: each of those values has exactly one place it is allowed to appear, some of them are legally significant, and at least one of them — the series and number — is what makes the document a document rather than a description of one.

Translation as prose preserves the words. It does not preserve the places. The failure is not that the output is wrong; the failure is that the output is no longer checkable against the source, which for a certified translation is the entire point.

There is a second, quieter problem. A scan has no layout to preserve in the first place. A photographed passport page is pixels. There is no document structure to carry across, because there is no structure in the file — only the structure a human sees when they look at it. Any approach built on "keep the original formatting" has nothing to keep.

Three outcomes, decided by what you uploaded

In practice a document translation pipeline has three possible endings, and which one you get is decided before any translation happens:

Input	What comes out
A scan or image-PDF that matches a known form	The form's own template is filled field by field
Anything that is or becomes a DOCX, with no matching form	The translation is written into the original file's XML in place, so the formatting survives
Everything else — `.txt`, `.csv`, `.xlsx`, `.json`, `.po`	A plain text file

Two things about that table are worth saying out loud, because both are routinely misread.

"No template" does not mean "no formatting." A DOCX with no matching form comes back as a DOCX with its formatting intact. What the template adds is not layout survival — it is field-level extraction and a form built for that specific document type. That is what makes scans work, and scans are the case where nothing else can.

Templates are for scans. In our own pipeline, template filling is gated on the document being an image-PDF. A PDF that carries a real text layer, or a DOCX, takes the in-place replacement path even when a template would have matched — because in-place replacement is strictly better when there is a layout to replace into.

What a template actually is

A template is three things, and it is worth separating them because they fail in different ways.

A DOCX form with placeholders. The target-language document, laid out like the original, with {{surname}} where the surname goes. Filling it is mechanical.

A field schema. A list of the values this document type has, their types, and which are required. This is what the extraction is scored against — a field declared and not delivered is a visible gap rather than a silent one.

An extraction prompt. The instruction that turns a page image into those fields.

We ship 16 of these, covering three language pairs: eleven Russian-to-English (certificates from the civil registry, a passport, four cadastre extracts, a company-registry extract), four Korean-to-Russian (export declaration, certificate of origin, invoice, packing list), and one Chinese export customs declaration.

The mechanical part is more mechanical than it sounds and less than you would like. Placeholders live inside merged table cells, inside headers and footers, and — because of how word processors store text — a single {{exporter_address}} is routinely split across three separate runs of characters in the file. Anything that fills these has to reassemble placeholders before it can substitute them, and anything that edits them has to put them back the same way.

What it costs, on a real document

Here is one full run, measured end to end on a Chinese export customs declaration going to Russian:


Fields extracted	45
Translatable segments	44
Output	A filled DOCX form, 557 words
Cost	$0.0244
Wall clock	256 seconds
Numbers preserved	26 of 28

The last row is the one that matters and the one that is usually not reported. A customs declaration is mostly numbers: HS codes, quantities, weights, amounts, a company registration code. Twenty-six of twenty-eight source numbers appeared unchanged in the output. Of the two that did not, one was a date deliberately reformatted (20260702 → 02.07.2026) and one was a real loss: a second company code in a field the form had no slot for.

That second one is the honest lesson of the whole approach. The extraction found the value. The form had nowhere to put it. A template can only deliver what it has a box for, and a missing box looks exactly like a missing value from the outside.

Choosing the right form is its own problem

With sixteen forms, something has to decide which one a document is. That decision is cheaper and dumber than people expect: weighted keyword scoring, with a per-form threshold and a list of exclusions. No model call. It runs in milliseconds and it is right almost all the time.

Almost.

We recently ran an extract from the register of individual entrepreneurs — six pages, Russian — through our own matcher, and it chose the passport template, confidently, at 0.367 against a 0.3 threshold. The document contains no passport. It contains no "паспорт", no issuing authority line, none of the words that identify a passport.

What carried it there was that the register extract quotes the entrepreneur's identity document, under a heading that mentions a citizen of the Russian Federation. Two generic phrases, appearing three times each, out-scored a form none of whose distinguishing keywords matched at all.

The immediate fix is an exclusion, and that is what we shipped. The real lesson is structural: a weighted sum can clear a threshold without a single identifying term matching. If you build this, score the presence of distinguishing terms, not just the total.

The failure mode nobody warns you about

Here is the one we did not see coming, and the reason this section exists.

A template gets built by taking one real translation — a document a human translator already produced — and replacing its values with placeholders. It is the fastest way to build a form and it produces good forms. It also has a trap: whatever value the author forgets to replace stays in the template, and is then asserted about every document that form ever renders.

We swept all sixteen of ours looking for exactly that. Fifteen were clean. One was not: a notarised consent for a minor to travel abroad, which printed

place of birth: Vladivostok — for both parents and the accompanying adult;
a gender pinned to position rather than read from the document;
and, in the seal block, a named notary with their tax number, while the working notary placeholders sat unused two paragraphs below.

Every consent that form produced said those things, about whoever the document was actually about. Nothing looked wrong. A form that prints a plausible city looks precisely like a form that read one — which is what makes this class of defect survive review.

If you run templates, the check is worth automating: flatten each form, blank out the placeholders, and look at what concrete-looking text remains. Most of what you find will be legitimate pre-printed furniture — "PASSPORT OF A CITIZEN OF THE RUSSIAN FEDERATION" belongs on the passport form. The rest is somebody's birthplace.

When a template is the wrong tool

Templates are narrow on purpose, and the honest positioning is that narrowness:

They cover document types you have a form for. Sixteen forms is sixteen forms. A document outside that set goes down the in-place path, keeps its formatting, and gets no field-level extraction.
They need the document to actually be that type. See the matcher section — a confident wrong answer is worse than no match, which is why "no template" has to be an acceptable outcome rather than a failure.
They do not reconstruct layout. Having a model rebuild the structure of a document whose layout conversion could not recover is a different problem, and one we do not claim to solve.

For a contract, a report, or a letter, in-place DOCX replacement is the right answer and a template would add nothing. For a scan of a customs declaration, it is the only answer that produces something the receiving officer can check.

Key Takeaways

An official document is a form, and its meaning is positional. Translating it as prose keeps the words and loses the checkability, which is what a certified translation is for.
Templates exist for scans. When a file has a real layout, replacing text in place preserves it better than any form could. Templates earn their keep exactly where there is no layout to preserve.
A template can only deliver what it has a box for. Declare the fields and the placeholders together, and audit that every extracted field has somewhere to land.
Form selection deserves as much scrutiny as extraction. A weighted keyword score can pick a form without matching a single distinguishing term; measure that, do not assume it.
Audit your forms for values left behind. A template traced from a real document inherits that document's facts unless someone checks, and the defect is invisible from the output side.

FAQ

What is template-based document translation?

It is translating a standard document by extracting its field values, translating those values, and filling a purpose-built form in the target language — rather than translating the document as running text. It is used for documents whose layout is fixed and legally meaningful: certificates, declarations, registry extracts.

Does translating a DOCX without a template lose its formatting?

No. A DOCX with no matching template is translated in place, inside the file's own XML, so the formatting survives. What a template adds is field-level extraction and a form designed for that document type — which matters most for scans, where there is no layout in the file to preserve at all.

Why not just have an AI rebuild the layout?

Because "rebuild the layout" and "preserve the layout" are different problems with different failure modes. Preserving works when structure exists in the file. Rebuilding is what you need when conversion could not recover the structure, and it is an open problem rather than a shipped feature — treat any vendor claiming otherwise with suspicion.

How do you know a template picked the right document type?

You measure it against real documents, including the ones you expect to fail. Our own matcher confidently routed a business-registry extract to a passport form while matching none of that form's identifying keywords — a defect visible only by running the corpus through and reading what came out.

How many numbers survive a document translation?

On our measured Chinese customs declaration run, 26 of 28 source numbers appeared unchanged in the output; one more was a deliberately reformatted date. The one true loss was a value the form had no field for. Numeric integrity is measurable, and it is the metric worth demanding — accuracy scores on prose say nothing about whether an HS code survived.

Conclusion

The distinction between translating a document and filling a form sounds like an implementation detail, and it decides whether the output is usable. Prose translation optimises for reading; document translation has to optimise for checking, because someone will hold the two versions side by side and compare box to box.

That is also why the interesting engineering is not in the translation step. It is in choosing the right form, giving every extracted value somewhere to land, and making sure the form itself is not quietly asserting facts about a stranger.

If you translate certificates, declarations or registry extracts and you want to see what field-level extraction produces on your own documents, try KTTC — the output is a filled form you can check line by line, which is the only kind worth having.