How to Translate AsciiDoc Files and Keep the Build

Quick answer — AsciiDoc translation has to protect attribute definitions and references, include directives, conditional blocks and delimited source blocks. All four look like ordinary text in a plain-text file, which is what makes them easy to damage.

More syntax than it looks

AsciiDoc reads like prose and carries a great deal of structure: attribute entries at the top of a file, attribute references inline, includes pulling in other files, conditional directives, and several kinds of delimited block.

None of it is visually distinct the way a code fence is, so a process treating the file as text will translate parts of the machinery.

Attributes are variables

:product-name: Vitra defines an attribute; {product-name} references it. The definition's value is usually content and should be translated once. The reference is a token and must survive exactly. Translating {product-name} to {nom-du-produit} produces a literal brace expression in the output, because no attribute by that name exists.

Includes assemble the document

include::chapter-one.adoc[] pulls another file in at build time. The path is a path and must not change unless the translated files genuinely live elsewhere — in which case every include across the set needs rewriting consistently.

Line-range and tag-based includes add a wrinkle: include::file.adoc[tag=setup] depends on tag comments inside the target file surviving translation.

Conditionals

ifdef::, ifndef:: and ifeval:: wrap content shown only under certain attributes. The wrapped content still needs translating, and it will not appear in a rendered preview unless the condition is met.

Reviewing the rendered output alone therefore misses it.

Source blocks and callouts

Delimited source blocks stay verbatim. Callouts — the numbered markers pointing at lines of code, with descriptions below — are the exception: the marker stays and the description translates.

Getting that backwards renumbers the callouts and detaches them from the lines they annotate.

Cross-references and anchors

<<section-id>> resolves against an anchor. Auto-generated anchors derive from heading text, so translating a heading changes the anchor and breaks every reference to it. Define explicit IDs in the source if the set is large.

Why documentation repeats

Prerequisites, procedures, parameter tables and troubleshooting sections recur across a docs set and across versions. translation memory returns them unchanged so work tracks the diff, and terminology stays identical across hundreds of pages.

Setup notes are on the AsciiDoc translation integration page.

Tables and their formatting

AsciiDoc tables use a column specification declaring widths and alignment. The spec is structure; the cell content is text. A longer translated cell does not break the table but it does change how the widths render. Where a table is tightly specified, review the built output rather than the source. Document translation preserves the specification while the cells change.

Docs-as-code review

Because AsciiDoc lives in version control, a translation update arrives as a pull request and can be reviewed like code. That is a real advantage over document formats, and it means a reviewer sees exactly what changed.

Attribute-driven output variants

A docs set can produce several outputs from one source by setting attributes at build time. Each variant may need its own review, because a conditional block excluded from the default build still ships somewhere.

List the build targets before scoping. There are usually more than the documentation team mentions unprompted.

Where to start

Build the translated set and compare the output page count against the source. A mismatch means an include or a conditional did not resolve.

FAQ

What is different about AsciiDoc versus Markdown? It carries far more structure in plain text: attribute definitions and references, include directives, conditional blocks and several delimited block types, none of which is visually distinct the way a code fence is.

How are AsciiDoc attributes handled? The definition's value is usually content and translated once; the inline reference is a token that must survive exactly. Translating a reference produces a literal brace expression because no attribute by that name exists.

Do conditional blocks need translating? Yes, if the content ships under any condition. They will not appear in a rendered preview unless the condition is met, so reviewing only the rendered output misses them.

What happens to callouts in source blocks? The numbered marker stays and the description below it translates. Reversing that renumbers the callouts and detaches them from the lines of code they annotate.