Translate AsciiDoc files with Hyperlocalise

​

Source file

= Product guide
:product-name: Widget

Welcome to the setup guide.

== Install

Read link:https://example.com[the setup guide] to get started.

NOTE: Remember to save your work.

​

Configure your files

locales:
    source: en-US
    targets:
        - es-ES

buckets:
    messages:
        files:
            - from: locales/en-US/messages.adoc
              to: locales/{{target}}/messages.adoc

llm:
    profiles:
        default:
            provider: openai
            model: gpt-5.2

​

Translate

hyperlocalise run --dry-run
hyperlocalise run

​

Behavior and limitations

• Translates document titles, headings, paragraphs, list items, description lists, table cells, admonitions, and block titles.
• Consecutive non-blank lines form one paragraph. The translated paragraph is written as a single line.
• Comments, attribute definitions, block macros, preprocessor directives, YAML front matter, and verbatim blocks stay unchanged.
• Inline code, links, cross references, attribute references, bare URLs, anchors, passthroughs, and issue references such as #4580 are protected as placeholders. Link labels stay translatable.
• include:: directives are preserved. Included files are not resolved. Upload each file on its own.
• Segments use structural keys such as adoc.title and adoc.paragraph. Review generated files when you restructure source content.

​

Next steps

• Check translations before committing generated files.
• Local translation workflow explains repeat runs.
• Browse all file formats.

​

Related formats

• Markdown
• MDX
• HTML