Description

multifariousAsciiDoc File Type for Trados Studio – user guide

1. Description

AsciiDoc is how a great deal of developer-facing documentation is written: software manuals, API references, knowledge bases, books, the documentation sites of open-source projects. The file that arrives is a .adoc document – plain text, but plain text in which prose and structure share the same stream. A heading, a paragraph, a list, an admonition, a table, a code listing and an attribute reference all sit side by side, each told apart from the next by a marker at the start of a line or a character in the middle of a sentence.

Translating that file by hand means picking the sentences out of the markup and putting them back correctly. Extracting too much offers delimiters, markers, attribute names and code for translation.

multifariousAsciiDoc File Type reads a .adoc file the way Asciidoctor reads it, block by block and line by line, so that what reaches you is prose, and what does not reach you is untouched. You translate in Trados Studio with your translation memory, your termbase and your QA, and see the page as you go.

The Studio editor with an AsciiDoc document open, source paragraphs on the left, target segments on the right, and the document rendered in the Preview pane. 

2. What it reads, and what it delivers

Input	How it is handled	What you get back
.adoc, .asciidoc, .asc	Read as a character stream, block by block	The same file, with only your translated text substituted
.txt	Accepted when the setting is on and the file opens with AsciiDoc syntax	The same

The target is your source file with the translated sentences swapped in, and nothing else changed. The document is not parsed and written out again, so nothing a rewrite would normalise is touched: the encoding, the byte-order mark, the mix of CRLF and LF line endings, the blank lines, the indentation inside blocks, the spacing around a delimiter.

A file you open and save without translating anything comes back byte for byte identical. That is checked against every file in the test corpus on every change to the code.

There are two exceptions, both explained in this guide. A paragraph written over several lines is written back on one line under the default line-break setting (section 7). And the underline of a two-line title is made longer or shorter to match the translated title, because Asciidoctor otherwise stops reading it as a title (section 4).

3. Installation

1. In Trados Studio, open Add-Ins > AppStore and search for multifariousAsciiDoc File Type for Trados Studio. Or download the .sdlplugin from the AppStore website and double-click it.

2. Install, then restart Trados Studio – plugins are read at startup.

3. Confirm it is there: File > Options > File Types. You should see AsciiDoc in the list, with one page beneath it, AsciiDoc content.

File Types in Options, with AsciiDoc in the list and the AsciiDoc content page selected.

System requirements: Trados Studio 2026 on Windows 10 or later. Nothing else is needed: the plugin does not run Asciidoctor or any other processor, and installs nothing beyond itself.

4. What gets translated – and what does not

Read this section before your first project.

Translated

• The document title and every section title, in both the == Title form and the two-line form with an underline.

• Paragraphs of prose, including the text of an admonition after its NOTE: label.

• Block titles, the .Title line above a table, an image or a listing.

• Every item of every list – unordered, ordered, checklist, callout – and both the term and the description of a description list.

• Table cells, in all four table formats: PSV, CSV, DSV and TSV. A cell marked a| is read as blocks and its paragraphs and lists are offered as such.

• Verse blocks, line by line, and the attribution and citation of a quote or verse.

• Image alt text and titles, on block images and inline images alike.

• Captions given as attributes.

• Footnote text, kept inline in the sentence carrying its marker.

• The text of a link: https://example.org[the site] gives you the site and locks the address.

• Visible index terms, which are words a reader sees, and hidden index terms too by default, since an index in the source language is of no use to a reader of the translation.

• The values of the document attributes you name on the settings page: description and keywords by default.

Not translated

• Markup and structure. Delimiters, list markers, admonition labels, attribute entry names, the quote marks of a quoted paragraph, the > of a Markdown-style quote, the quotes of a CSV cell. These sit outside the segments or inside tags, and nothing you type can reach them.

• Attribute references such as {product-name}, which are always a tag whatever attributes are listed.

• URLs, email addresses and character references such as &, each a single tag.

• Passthroughs: +one plus+, +++three plus+++, pass:[] and $$legacy$$ inline, and the ++++ block, protected whole unless you turn on the embedded HTML option (section 7).

• Code: listing, literal and source blocks, literal paragraphs and fenced blocks, protected whole unless you turn on extraction (section 7).

• Comments and directives: // lines and //// blocks, include::, ifdef:: and the other conditional directives, block macros other than the alt text of an image, anchors, cross-reference targets.

• Author and revision lines under the document title.

The title whose underline moves

A two-line title is a line of text with a line of =, -, ~, ^ or + beneath it, and Asciidoctor reads the pair as a title only while the two lines are within one character of each other in length. A translation is rarely the same length as its source, so the plugin makes the underline longer or shorter by exactly the change in the title. It is the one part of the file that is regenerated rather than copied, and it keeps whatever offset the author had.

The segments of a document with both title forms, with the document structure column showing “Section title (level 1)”. 

5. Your first project

1. Create a project as you would for any file, adding the .adoc document.

2. Open it in the editor. The document structure column on the right of each segment tells you what you are looking at: Document title, Section title (level 2), Paragraph, Admonition: NOTE, List item (level 1), Term, Table cell, Attribute value: description, Image alt text, Verse.

3. Translate. Everything that is not prose is a tag or is outside the segment.

4. Save the bilingual file (Ctrl+S), then Save Target As.

Reading the segments

Tags carry the document’s own markup. A * and its closing * are the two halves of a tag pair, and the text between them is yours to translate. A link’s opening tag holds https://example.org[ and its closing tag holds ]; the words between are the link text. Turn on full tag text in Studio (View > Tag Display Mode) if you want to see exactly what each one holds.

Formatting looks like formatting. *bold* shows as bold, _italic_ as italic, `monospace` in a monospace font, #highlight# with a highlight, ^super^ and ~sub~ raised and lowered. The unconstrained doubled forms, **b**old, work the same way.

Placeholders stand for what they hold. An attribute reference, an escaped character, a passthrough, a URL, an email address, a character reference, an image, an anchor: each is one tag carrying exactly the text it replaces. Leave them where they are, or move them within the segment when the translation needs the URL or the image somewhere else.

A hard line break ends the segment. A line ending in + is a line the reader sees, so the text before it and the text after it are two segments, with the break marker and the line break as tags between them. In a verse and in a paragraph with the hardbreaks option, every line is a segment of its own.

A paragraph with hard line breaks shown as separate segments, with the break tags between them. 

You cannot break the document by typing. A star, an underscore or a backtick that would pair up in your translation is escaped on the way out, so *not bold* typed into a segment reaches the file as \*not bold* and renders as itself. A translated line that would open a list or a title – one that begins with * or == – is guarded with an empty attribute reference, which renders as nothing. A | typed into a PSV table cell is escaped so it cannot end the cell. The one thing to avoid is deleting tags, because those are the document’s markup rather than your text.

Comment lines inside a paragraph stay where they are. A // line between two lines of one paragraph is a tag in the gap between them, never joined and never lost.

Adding formatting

Select a word in a target segment and press Ctrl+B or Ctrl+I, or use the QuickInsert toolbar, which also has a Monospace button. The marks are inserted around your selection, and the result is ordinary AsciiDoc:

Coastal *erosion* affects _thousands_ of `kilometres` of shoreline.

This works in a document that contains no formatting at all: the tags do not have to exist in the source for you to use them.

The QuickInsert toolbar with the Bold, Italic and Monospace buttons, and a target segment with formatting added. 

6. The preview

The preview shows the document as a page: headings, paragraphs, lists, tables, admonitions, code blocks, quotes and verse, with inline formatting and links, and attribute references resolved from the document’s own header.

Using it

Open the Preview pane and choose AsciiDoc preview in the View list.

• Target shows your translation in place, with the source where you have not translated yet.

• Source shows the document as it was delivered, for comparison.

• The active segment is highlighted on the page, and the page scrolls to it as you move through the editor.

• Click on the page to select that segment in the editor.

• The page is regenerated when you confirm a segment, and when you press Refresh beside the View list. An edit you have typed but not confirmed is not on the page yet, tags and words alike.

What it is, and is not

The page is a structural rendering made by the plugin, not Asciidoctor’s output. It shows where things are and what they say, so you can read your translation in place; it does not show a site’s stylesheet, its fonts or its images. An image is shown as a labelled box with its alt text. A code block is shown as code. Nothing is loaded from outside the page.

Segments that live inside embedded HTML (section 7) have no preview while they are selected: Studio takes the preview from the file type that owns the segment, and its HTML file type has none for embedded content. Select an AsciiDoc segment and the page comes back. The Target tab does show the translated HTML in its block.

The side-by-side tab is not offered.

7. The settings, in depth

File > Options > File Types > AsciiDoc > AsciiDoc content. One page, seven groups, and beneath each group a collapsible panel headed by a question that explains the AsciiDoc concept in plain terms.

Settings are stored per file type configuration and are copied into a project when its files are converted. Decide them before creating the project: changing them afterwards does not reach a file that already exists.

The AsciiDoc content settings page with one help panel expanded.

Document attributes

Attributes whose values are translated, one name per line – description and keywords by default.

Most attributes hold configuration: a version number, an image folder, a switch. Those are never translated. Some hold prose that readers see: description and keywords feed the page metadata of a published site, and teams add their own such as a summary or a subtitle. Name those here and their values become segments. A name matches without regard to case, and an entry containing characters other than letters, digits, hyphens and underscores is read as a regular expression, so meta-.* covers every attribute beginning with meta-.

Attribute references such as {product-name} inside the text are always protected as tags, whatever is listed here.

Code and literal blocks

Extract the text of listing, source and literal blocks – off by default.

Code is not prose, and a translated variable name breaks a program. Off, every code block is protected whole. On, each block becomes one segment, with each line one run of text and each line break a tag, and nothing inside it is treated as markup: a star in a listing is an operator, a brace is a block, a URL is a string. Turn it on for documents whose listings hold console output, sample messages or configuration files with comments a reader needs, and expect to leave most of each segment as it is.

Line breaks within a paragraph

Join the lines into one segment (default) or Keep each line break as a tag.

AsciiDoc authors often write one sentence per line, and the published page joins them with a space. Joined, a translator sees the paragraph whole and segmentation follows the sentences; the translation is written on a single line, and this is the one place the translated file differs from the source beyond the words. Kept as tags, the breaks survive into the translation and a diff of the translated file shows only the words that changed; sentences then end mid-line, which is how the source was written. Choose the second when the file lives in version control and reviewers diff it line by line.

Line breaks that carry meaning are always kept whatever is chosen: after a hard line break marker, in a verse, in a paragraph with the hardbreaks option, in code, and where a comment line sits between two lines of text.

Monospace text

Protect monospace text matching this regular expression – empty by default.

AsciiDoc authors put file names, commands, keys and code in `monospace`. Most of that must stay exactly as written, and a translator who is shown it may change it by accident. Some authors also use monospace for menu labels or literal phrases that do need translating, which is why nothing is protected by default. The pattern is matched against the text between the backticks. What matches becomes one tag; what does not stays a pair of tags with the words between them editable. A pattern such as ^[\w./-]+$ makes file names, commands and identifiers single tags. A pattern that does not compile is reported under the box as you type.

Index terms

Translate hidden index terms – on by default.

Hidden terms are written as (((term))) or indexterm:[term] and appear only in the index. Visible terms, written as ((term)), are part of the text and are always translated. Turn this off when the index is generated elsewhere, or when a project has agreed that index work is a separate job; the hidden terms then become single protected tags.

Passthrough blocks

Translate the HTML in passthrough blocks with Studio’s HTML file type – off by default.

A ++++ passthrough block hands its content to the output untouched, and in a document published as HTML it usually holds HTML: a table the AsciiDoc syntax cannot express, an embedded video, a styled callout. Text a reader sees can be inside it. Turned on, that content is translated with Studio’s own HTML file type, under the settings of the HTML Embedded Content file type in the same project, and its segments appear beneath the block. The translated HTML is written back in place. Inline passthroughs stay protected either way, since they sit inside a sentence.

Two things to know. The block’s content then comes back from the HTML file type rather than from this one, so it is written the way that file type writes HTML and may differ from the source in spacing or entities; an ß may come back as ß, which is the HTML file type’s entity setting and can be changed there. And while one of those segments is selected the preview pane is empty (section 6).

A document with the passthrough option on, showing the HTML segments beneath the block in the editor. 

Plain text files

Treat .txt files as AsciiDoc when they look like it – off by default.

AsciiDoc was designed to read well as plain text, and its author once encouraged the .txt extension; some older documentation sets still use it. A .txt file is taken as AsciiDoc only when its opening lines hold a title, an attribute entry, a block delimiter or another AsciiDoc marker. Plain prose stays with the Plain Text file type. With the option on, Studio’s file type order decides which file type is asked first; put AsciiDoc above Plain Text if the .txt files in a project should come here.

8. Saving the target

1. Save the bilingual file first (Ctrl+S). Studio generates the target from the last-saved state, so an editor tab showing an asterisk means edits that will not reach your target.

2. File > Save Target As, and choose where the .adoc goes.  Or use the Generate Target Translations batch task to add the target documents into the respective language folders of your Studio project.

3. The delivered files are your source documents with the translated spans substituted: same encoding, same line endings, same everything else, apart from the two exceptions in section 2.

9. Verifying what you deliver

The Target tab of the preview shows exactly what saving would produce, so a document that reads correctly there is a document whose structure survived.

If you would rather check outside Studio, open the delivered .adoc in any AsciiDoc tool – Asciidoctor, an editor with AsciiDoc preview, or the documentation site’s own build – and render it. It should render exactly as the source did, with your words in place. A diff of the target against the source is the quickest check: under the default line-break setting it shows changed paragraphs, and under the tag setting it shows changed lines and nothing else.

10. Workflow recipes

Piloting a new client’s documents. Run one representative file through first and look at the segments before quoting. AsciiDoc documents vary in how much of their content is prose: an API reference may be mostly listings and tables, a manual almost entirely paragraphs.

A documentation set that keeps prose in attributes. Open one file and read its header. Any attribute holding a sentence a reader sees – a summary, a subtitle, a meta description – goes on the attribute list before the real project is created.

Files under version control. Choose “Keep each line break as a tag” so the pull request that carries the translation diffs line by line.

Translation memory. A paragraph is one segment under the default setting and Studio segments it into sentences as usual, so a TM built from other formats applies normally. Under the tag setting each source line is still part of the same segment, with the breaks as tags, so leverage is unchanged but the tags must be placed.

Working without any AsciiDoc knowledge. You need none. Treat every tag as something to keep, translate the words, and use the preview to see the result.

11. Troubleshooting

The preview pane says there is no preview available. The selected segment belongs to embedded HTML. Select an AsciiDoc segment and the page returns. See section 6.

A paragraph written over several lines comes back as one line. That is the default line-break setting, and AsciiDoc renders both the same. Choose “Keep each line break as a tag” before creating the project if line-by-line diffs matter.

I changed a setting and nothing happened. A bilingual file carries its own copy of the settings from when it was created. Change the setting and create the project again.

Something I expected to be protected was offered for translation. For monospace text, add a pattern. For an attribute value, remove its name from the list. Failing both, return the segment unchanged: an unchanged segment is not written back at all.

A star or underscore I typed shows with a backslash in the file. That is the escape that keeps your text from becoming formatting. It renders as the character itself.

My translated file renders a title as a paragraph. Only possible with a tag deleted or a title’s text moved onto another line. The plugin keeps a two-line title’s underline in step with the title; check the segment’s tags with Studio’s tag verification.

12. Limitations

Version 1.0.0. What this does not do:

• The preview is a structural rendering, not Asciidoctor’s output with the site’s stylesheet. It shows where things are and what they say.

• No preview while an embedded HTML segment is selected. Studio’s rule for embedded content, not the plugin’s; the page returns on any AsciiDoc segment.

• No side-by-side preview.

• Inline passthroughs are always protected. +++<b>text</b>+++ inside a sentence stays a tag even with the passthrough option on, since embedded content cannot sit inside a segment.

• A paragraph given the [pass] style is offered as prose. Its content is usually raw HTML, and a later version will treat it like a passthrough block.

• Attribute values are offered by name only. There is no guessing which attributes hold prose; list them.

• Author and revision lines are not offered. A name is not translated, and a revision remark rarely is.

• include:: is not resolved and conditional directives are not evaluated; the included file is translated on its own, and the text inside a conditional is offered as it stands.

• The translations of this plugin’s own interface are into nine languages and have been checked against Studio’s own terminology.

Your documents will use conventions the corpus does not cover. If something behaves oddly, please say so: a document that segments strangely, a construct that should be protected, an attribute that should or should not be offered. A sample file is the most useful report.

Feedback and questions: https://multifarious.filkin.com/product/asciidoc-file-type/

multifariousAsciiDoc File Type for Trados Studio. Copyright 2026 multifarious. All rights reserved.

Nothing is bundled with the plugin and nothing is installed by it. The reading rules follow Asciidoctor’s parser, and the test suite checks every corpus file against Asciidoctor.js, which is used for verification only. The translation path uses no third-party library at all: fidelity comes from substituting translated text into the original byte stream.