AsciiDoc is a plain-text authoring format used mainly for technical documentation, such as software manuals, API guides, and books. It is comparable to Markdown but with a richer feature set, including tables, admonitions, cross references, includes, and attributes. It is the format behind Antora and Asciidoctor documentation sites.

Content parsing

What is ingested for translation

Smartling extracts the following content from AsciiDoc files as translatable strings:

• Paragraph text
• Headings and block titles
• List items, including bulleted, numbered, description lists, and callouts
• Table cell contents
• Admonition text (NOTE, TIP, WARNING, and similar blocks)
• The document title and author line

What is not ingested for translation

The following content is preserved exactly as it was uploaded and is not sent for translation:

• Code blocks and other verbatim blocks
• Comments
• Attribute definitions and block attributes
• Block macros
• Preprocessor directives
• YAML front matter

How content is split into strings

A string is a paragraph, not a line. AsciiDoc treats consecutive non-blank lines as a single paragraph, so a paragraph that the author hard-wrapped across several lines is presented to the translator as one string rather than several fragments.

Because a paragraph becomes a single string, the translated file will not preserve the original line wrapping. A translated paragraph is written out as one line. This does not affect the rendered output, which is unchanged.

Placeholders

Smartling automatically protects inline markup so translators cannot break it. The following are protected by default:

• Inline code, for example `widget --start`
• Links, cross references, and other macros. The visible link text stays translatable; only the markup around it is protected.
• Attribute references, for example {product-name}
• Bare URLs
• Inline anchors and passthrough content
• Issue references, for example #4580

A link's visible label is still translatable. For link:https://example.com[the setup guide], the translator sees "the setup guide" between two placeholders.

Custom placeholders

You can protect your own patterns in addition to the default set above, using the placeholder_format_custom directive with a regular expression. Custom patterns are added to Smartling's built-in protection rather than replacing it.

Unlike some other file types, AsciiDoc does not currently support directives embedded in the source file. This directive must be supplied when the file is uploaded (for example, as an API parameter or in a directive template), not written inside the .adoc file itself. If you're coming from Markdown, note that in-file directives are not available for AsciiDoc.

Known limitations

• Emphasis is not yet segmented. Bold and italic markers (*bold*, _italic_) currently appear in the translatable text rather than being protected as placeholders.
• Hard line breaks and callout markers are not yet handled.
• Backslash escapes are not yet handled. A backslash used to escape a character (for example, \*not emphasized\*) is not recognized, so the escape is not suppressed and the backslash reaches the translator as literal text alongside the markup it was meant to protect.
• Passthrough blocks (++++) are treated as verbatim, so any text inside them, including visible HTML link text, is not offered for translation.
• Included files are not resolved. Each file is parsed on its own. include:: directives are preserved, but the included file is not pulled in. If you use Antora or a multi-file book setup, upload each file individually.
• Files with no translatable content are rejected with the error "No source strings found." The most common case is an Antora nav.adoc navigation file, which is a list of cross references with no visible text of its own. This is expected. If you're syncing a whole documentation repository, you may see these errors for navigation files, and they are harmless.

Translation import

AsciiDoc does not support keys or variants, so it cannot be used with the translation import endpoint. It is upload-and-download only.

For more information on the terms used in this article, see Introduction to Strings & String Uniqueness and Localization & Resource Files: Parsing Behavior.