> ## 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 Flutter ARB files with Hyperlocalise

> Translate Flutter resource bundles while retaining message metadata.

Application Resource Bundle (ARB) files store Flutter messages and their metadata in JSON. Hyperlocalise translates message values while carrying message metadata through writeback and updating the target locale.

Supported extensions: `.arb`.

## Source file

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

```json theme={null}
{
    "@@locale": "en-US",
    "welcome": "Welcome",
    "@welcome": {
        "description": "Home screen heading"
    }
}
```

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

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

* Top-level message keys are translated. Keys beginning with `@`, including `@@locale` and `@message` objects, are metadata.

* Writeback preserves target metadata and carries source metadata forward for newly added messages.

* `@@locale` is updated to the target locale. Keep ICU placeholders and plural expressions in the message strings.

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

* [JSON localization](/cli/reference/formats/json)
* [Android XML string resources](/cli/reference/formats/android-xml)
* [Apple String Catalog (.xcstrings)](/cli/reference/formats/apple-xcstrings)