> ## 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 TOML localization files with Hyperlocalise

> Translate string values in TOML locale files while preserving tables, comments, and quoting.

TOML stores keyed configuration and locale strings with tables and typed values. Hyperlocalise translates string leaves and leaves numbers, booleans, dates, and comments in the file structure.

Supported extensions: `.toml`.

## Source file

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

```toml theme={null}
hello = "Hello"

[home]
title = "Welcome"
greeting = "Hello, {name}!"
items = ["Open your project", "Start translating"]
```

## 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.toml
              to: locales/{{target}}/messages.toml

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.

Hyperlocalise Platform native projects also accept `.toml` uploads for file
translation jobs and segment review. See [Supported formats](/platform/file-formats).

## Behavior and limitations

* Nested tables flatten as dotted keys, for example `home.title`. String arrays use bracket indexes such as `home.items[0]`.

* Only string values are translated. Numbers, booleans, dates, and other non-string scalars stay in the file.

* Writeback replaces existing string literals in place and preserves comments, table headers, and quote style when the translated value still fits that style.

* Array-of-tables (`[[name]]`) and duplicate keys are rejected. New keys append as dotted assignments at the end of the file.

## 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

* [YAML localization](/cli/reference/formats/yaml)
* [INI](/cli/reference/formats/ini)
* [JSON localization](/cli/reference/formats/json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.