Translate TSV localization files with Hyperlocalise

TSV catalogs exchange messages in tab-separated rows and columns. Column structure determines which content Hyperlocalise treats as keys and translation values; use the source layout below before translating an existing spreadsheet export. Supported extensions: .tsv.

Source file

Save this example as locales/en-US/messages.tsv.

key	value
home.title	Welcome
home.greeting	Hello, {name}!

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

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 .tsv uploads for file translation jobs and segment review. See Supported formats.

Behavior and limitations

The example uses a header row with key and value. Fields are separated by tabs.
Locale-column layouts are also supported. Source and target locales select the corresponding columns.
Existing rows retain their order; newly appended keys are sorted. Quoting and line endings may be normalized.
This page covers translation files. For status --output csv, see Command output.

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