# How to Translate AsciiDoc Files and Keep the Build | Vitra.ai > AsciiDoc hides more syntax in plain text than Markdown does. Attributes, includes and conditionals all look like prose and none of it is as well. **Canonical URL**: https://www.vitra.ai/general/translate-asciidoc-files **Source**: This is the Markdown rendering of https://www.vitra.ai/general/translate-asciidoc-files, generated at build time from that page. --- 4 min read # How to Translate AsciiDoc Files and Keep the Build AsciiDoc hides more syntax in plain text than Markdown does. Attributes, includes and conditionals all look like prose and none of it is as well. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Senior Product Manager , Vitra.ai Updated Aug 17, 2026 ![How to Translate AsciiDoc Files and Keep the Build](https://www.vitra.ai/static/images/blog/translate-asciidoc-files.jpg) Table of contents [More syntax than it looks](#more-syntax-than-it-looks) [Attributes are variables](#attributes-are-variables) [Includes assemble the document](#includes-assemble-the-document) [Conditionals](#conditionals) [Source blocks and callouts](#source-blocks-and-callouts) [Cross-references and anchors](#cross-references-and-anchors) [Why documentation repeats](#why-documentation-repeats) [Tables and their formatting](#tables-and-their-formatting) [Docs-as-code review](#docs-as-code-review) [Attribute-driven output variants](#attribute-driven-output-variants) [Where to start](#where-to-start) [FAQ](#faq) Contributors [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Senior Product Manager Subscribe to our newsletter Subscribe > **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 `<>` 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](https://www.vitra.ai/features/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](https://www.vitra.ai/integration/adoc-translation) 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](https://www.vitra.ai/features/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. Our blog ## Lastest blog posts Tool and strategies modern teams need to help their companies grow. Automotive [Automotive Brochure Localization by Market](https://www.vitra.ai/automotive/automotive-brochure-localization) A car brochure is a spec grid, a legal footer and a photo library, all market-specific. What actually has to change, and why the layout decides the schedule. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 Automotive [Automotive Campaign Localization Across Markets](https://www.vitra.ai/automotive/automotive-campaign-localization) Campaigns run through national companies and dealer networks, so one master becomes hundreds of files. Where the offer text and the disclaimers actually break. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 Automotive [Car Service Manual Translation for Technicians](https://www.vitra.ai/automotive/automotive-service-manual-translation) A workshop manual is read mid-repair by someone with the car on a lift. What that demands of procedures, torque figures and fault codes, in every language. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 [View all posts](https://www.vitra.ai/blog/page/1) --- ## Structured data ```json { "@context": "https://schema.org", "@type": "Article", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://www.vitra.ai/general/translate-asciidoc-files" }, "headline": "How to Translate AsciiDoc Files and Keep the Build", "image": [ { "@type": "ImageObject", "url": "https://www.vitra.ai/static/images/blog/translate-asciidoc-files.jpg" } ], "datePublished": "2026-08-17T00:00:00.000Z", "dateModified": "2026-08-17T00:00:00.000Z", "author": [ { "@type": "Person", "name": "Samhitha J Bhatt" } ], "publisher": { "@type": "Organization", "name": "Vitra.ai", "logo": { "@type": "ImageObject", "url": "https://www.vitra.ai/static/images/vitra-v-logo.png" } }, "description": "AsciiDoc hides more syntax in plain text than Markdown does. Attributes, includes and conditionals all look like prose and none of it is as well." } ``` ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.vitra.ai" }, { "@type": "ListItem", "position": 2, "name": "General", "item": "https://www.vitra.ai/general" }, { "@type": "ListItem", "position": 3, "name": "How to Translate AsciiDoc Files and Keep the Build", "item": "https://www.vitra.ai/general/translate-asciidoc-files" } ] } ``` ```json { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "What is different about AsciiDoc versus Markdown?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "How are AsciiDoc attributes handled?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Do conditional blocks need translating?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "What happens to callouts in source blocks?", "acceptedAnswer": { "@type": "Answer", "text": "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." } } ] } ```