> ## 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 Apple String Catalogs with Hyperlocalise

> Translate Xcode string catalogs, plural variants, and device-specific messages.

Xcode String Catalogs store source strings and locale translations in .xcstrings JSON files. Hyperlocalise has a dedicated catalog parser; follow its locale and variation limits below instead of treating the catalog as generic JSON.

Supported extensions: `.xcstrings`.

## Source file

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

```json theme={null}
{
    "sourceLanguage": "en-US",
    "strings": {
        "welcome": {
            "localizations": {
                "en-US": {
                    "stringUnit": { "state": "translated", "value": "Welcome" }
                }
            }
        }
    },
    "version": "1.0"
}
```

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

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

* Reads source text from the source-language localization. Simple entries without one fall back to the catalog key.

* Plural, device, and substitution variants use stable `::` paths. Variants require a source localization.

* Writes translations under `localizations[targetLocale]`, preserving catalog metadata and other localizations. JSON whitespace and ordering are normalized.

* The example writes a separate catalog per target locale. The catalog format itself can contain multiple locales.

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

* [Apple .strings](/cli/reference/formats/apple-strings)
* [Apple .stringsdict](/cli/reference/formats/apple-stringsdict)
* [JSON localization](/cli/reference/formats/json)