Translate TOML localization files with Hyperlocalise

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.

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 for other layouts.

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 and set OPENAI_API_KEY in your project’s .env.local or shell. You can also configure another AI provider.

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.

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 before committing generated files.
Local translation workflow explains repeat runs.
Browse all file formats.

​Source file

​Configure your files

​Translate

​Behavior and limitations

​Next steps

​Related formats

Source file

Configure your files

Translate

Behavior and limitations

Next steps

Related formats