# 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 Published Aug 17, 2026 ![How to Translate AsciiDoc Files and Keep the Build](https://www.vitra.ai/static/images/blog/translate-asciidoc-files.jpg) In this guide Contributors [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Senior Product Manager Try the workflow, not just the idea. Start with 500 free credits to explore creation, translation and personalization in Vitra Universe. [Start creating free →](https://universe.vitra.ai/auth/sign-up)[Or use a free working template](https://www.vitra.ai/templates) > **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. Continue the topic ## Related guides Read the next explanation, example or review step for this subject. General [How to Translate PHP Files and Keep the Code Working](https://www.vitra.ai/general/translate-php-files) In PHP, strings live in code. The job is separating what a user reads from what the interpreter runs, and most projects have never done it as well. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 17, 2026 General [How to Translate YAML Files Without Breaking the Build](https://www.vitra.ai/general/translate-yaml-files) In YAML the keys are code and the values are content. Get that wrong and the application does not start, which is at least an obvious failure as well. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 17, 2026 General [How to Translate a PDF and Keep the Layout](https://www.vitra.ai/general/how-to-translate-a-pdf) Translating a PDF is easy. Keeping the columns, tables and page breaks intact is the part that goes wrong, and it depends on one thing in practice. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 17, 2026 [Browse the topic guides](https://www.vitra.ai/blog/topics) --- ## 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", "url": "https://www.vitra.ai/author/samhitha" } ], "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": "Translation & content workflows", "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." } } ] } ```