> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Translate HTML files with Hyperlocalise

> Translate visible HTML text while protecting inline markup.

HTML combines visible page content with markup. Hyperlocalise translates supported text while protecting document structure. Review the rendered page as well as the text diff.

Supported extensions: `.html`, `.htm`.

## Source file

Save this example as `locales/en-US/messages.html`.

```html theme={null}
<main>
    <h1>Welcome</h1>
    <p>Open <strong>your project</strong> to get started.</p>
</main>
```

## Configure your files

Use this `i18n.yml` for the example, or add its file mapping to your existing bucket.
See [path templates](/cli/configuration/path-templates) for other layouts.

```yaml theme={null}
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

[Install the CLI](/cli/getting-started/install) and set `OPENAI_API_KEY` in your
project's `.env.local` or shell. You can also configure another
[AI provider](/cli/providers/overview).

```bash theme={null}
hyperlocalise run --dry-run
hyperlocalise run
```

The dry run previews the work. The second command writes translations to the
configured target path and updates the lockfile.

## Behavior and limitations

* Extracts visible element text with stable `html.*` segment keys.

* Inline tags are protected during translation and restored during writeback.

* `script`, `style`, and `head` content are excluded. Comments and whitespace-only text are preserved.

* Translates element text; do not assume every attribute is a translatable field. Review the rendered result.

## Next steps

* [Check translations](/cli/commands/check) before committing generated files.
* [Local translation workflow](/cli/workflows/local-generation) explains repeat runs.
* [Browse all file formats](/cli/reference/formats/overview).

## Related formats

* [Markdown](/cli/reference/formats/markdown)
* [MDX](/cli/reference/formats/mdx)
* [Liquid template](/cli/reference/formats/liquid)