Translate HTML files with Hyperlocalise

​

Source file

<main>
    <h1>Welcome</h1>
    <p>Open <strong>your project</strong> to get started.</p>
</main>

​

Configure your files

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

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

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

​

Translate

hyperlocalise run --dry-run
hyperlocalise run

​

Behavior and limitations

• Keys are dotted tag paths, like markdown slots: html.body.h1, html.p, html.p.strong, html.p.strong.2, html.body.img.alt. The first occurrence of a path has no suffix.
• Inline tags start a new segment. For <p>Open <strong>your project</strong> to get started.</p> the keys are html.p (Open ), html.p.strong (your project), and html.p.2 ( to get started.). Punctuation-only text and entity-only cells such as   are skipped. Tags stay in the file around those text nodes.
• script, style, pre, and head content are excluded, including <title>. Comments and whitespace-only text are preserved.
• <img alt="..."> is extracted as html.*.img.alt. Do not assume every attribute is translatable. Review the rendered result.
• hl entries page.html --import-settings settings.json applies extra HTML filters. html.excludedElements names more tags to skip. html.icuSubfilter marks ICU-shaped values.

​

Next steps

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

​

Related formats

• Markdown
• MDX
• Liquid template
• SVG text