Skip to content
Back to top
View this page
Edit this page

# AsciiDoc

The Translate Toolkit is able to process AsciiDoc files using the asciidoc2po converter.

## Conformance

- Parses common AsciiDoc syntax elements for translation.

- Capable of handling nested containers, such as lists in lists, and other AsciiDoc features.

- Aims to extract all content relevant for translation, at the cost of also including some formatting. For example, *bold text* and `monospace` is included in the text to be translated.

- Aims to preserve formatting as far as possible during round-trip conversion.

- One translation unit per logical element (paragraph, heading, list item, etc.).

- Preserves document structure including block delimiters, attributes, and directives.

## Supported Features

The AsciiDoc converter supports the following elements:

Document Structure:

- Document headers (preserved but not translated)

- Section headings at all levels (`==`, `===`, etc.)

- Paragraphs with normalized whitespace

Lists:

- Unordered lists (`*`)

- Ordered lists (`.`)

- Description lists (`term:: definition`)

- Checklists (`[*]`, `[x]`, `[ ]`)

- Nested lists

- List continuation markers (`+`)

Block Elements:

- Code blocks (`----`)

- Literal blocks (`....`)

- Example blocks (`====`)

- Sidebar blocks (`****`)

- Comment blocks (`////`)

- Quote blocks (`____`)

- Passthrough blocks (`++++`)

Inline and Special Elements:

- Admonitions (`NOTE`, `TIP`, `WARNING`, `IMPORTANT`, `CAUTION`)

- Simple tables (pipe-separated cells)

- Attribute lines (e.g., `[NOTE]`, `[source,java]`)

- Conditional blocks (`ifdef`, `ifndef`, `ifeval`, `endif`)

- Anchors (`[[anchor-id]]`)

- Block titles (`.Title`)

- Comments (`//` and `////`)

Preserved Elements:

- Include directives (not translated)

- All block delimiter markers

- Attribute definitions

- Conditional directives

- Anchors and cross-references

- Comment blocks

## Limitations

- Table parsing is limited to simple pipe-separated format. Does not support: * Cell spanning * CSV-formatted tables * PSV-formatted tables (colon-separated) * Complex table layouts with merged cells

- Inline HTML and other complex inline elements are preserved but treated as part of the translatable text.

- Does not validate that translated text maintains the same AsciiDoc formatting as the source.

- Block delimiters must use consistent delimiter characters (e.g., ====, not ===== of different lengths).

## Best Practices

- Use standard AsciiDoc syntax for best compatibility.

- Keep list items concise for easier translation.

- Use admonitions consistently (NOTE, TIP, etc.).

- Avoid mixing different list types within the same list structure.

- Test translated documents with asciidoctor to ensure proper rendering.

## References

- The AsciiDoc Language Documentation

- Asciidoctor User Manual

- AsciiDoc Quick Reference