Translate your first file

This guide uses OpenAI and one JSON file. You need the CLI installed and an OpenAI API key. For another setup, choose an AI provider or a file format.

Working with a team? Connect the CLI to Hyperlocalise Platform to share source files, manage translation and review in a workspace, and pull project translations back into your repository. This guide covers standalone local translation.

1. Create a source file

From your project directory, create locales/en-US.json:

{
    "welcome": "Welcome",
    "greeting": "Hello, {name}!"
}

2. Configure the project

Create i18n.yml in the project root:

version: hyperlocalise@1.13.3

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

buckets:
    app:
        files:
            - from: locales/{{source}}.json
              to: locales/{{target}}.json

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

A bucket groups related source-to-target file mappings. This one reads locales/en-US.json and writes locales/es-ES.json. For an existing project, you can also use hyperlocalise init to scaffold a configuration, then adjust its file paths and provider.

3. Add your API key

Add the key to .env.local in the project root:

OPENAI_API_KEY=your-openai-api-key

Keep this file out of version control. The CLI reads .env and .env.local automatically; exported shell variables take precedence. See provider credentials for other providers.

4. Preview and translate

Preview the work:

hyperlocalise run --dry-run

Check that the plan includes your source file and Spanish target. Then generate:

hyperlocalise run

The CLI creates locales/es-ES.json and records progress in .hyperlocalise.lock.json. Translated wording can vary by model; the keys and {name} placeholder should remain intact.

5. Review the result

Open the generated file and review the diff. Check translation integrity and inspect progress:

hyperlocalise check
hyperlocalise status --output csv

Commit the source, configuration, translated file, and lockfile after review. When source messages change, repeat the preview and translation commands.

Continue

Project layout explains what to keep in your repository.
File formats covers other source types.
Local translation covers repeat runs and release preparation.
Connect to Hyperlocalise Platform gives your team a shared translation and review workflow.
TMS curation adds a shared review step.

​1. Create a source file

​2. Configure the project

​3. Add your API key

​4. Preview and translate

​5. Review the result

​Continue

1. Create a source file

2. Configure the project

3. Add your API key

4. Preview and translate

5. Review the result

Continue