# iOS app guide

The iOS platform supports AI-assisted translation of classic Apple `.strings` resources stored in locale-specific
`.lproj` directories. It uses the same translation core as Web and JVM projects while preserving Apple resource-file
formatting and encoding.

## Initial scope

The first iOS version supports:

- one locale-specific `.strings` table, normally `Localizable.strings`
- `translate`, `retranslate`, `improve`, and `validate`
- source-locale improvement with `improve --include-source-locale`
- `cleanup-phrase`, `test-catalog-connection`, and `test-ai-connection`
- UTF-8 with or without BOM and UTF-16 little- or big-endian files
- Apple string escapes and printf placeholders such as `%@`, `%d`, `%s`, and `%ld`

It intentionally does not yet support `.xcstrings` String Catalogs, `.stringsdict`, additional tables such as
`Settings.bundle/Root.strings`, unused-key removal, key harmonization, shared-message synchronization, or UI component
inspection.

## Initialize a project

Run the platform-aware setup from the app repository:

```sh
npx @rio-cloud/i18n init
```

Xcode projects with `.lproj/Localizable.strings` resources are detected as iOS projects. To bypass detection:

```sh
npx @rio-cloud/i18n init --platform ios
```

Initialization discovers the English source resource, sibling target locales, table name, exact `.lproj` directory
names, file encoding, an existing root-level Phrase configuration, the shared catalog, and the AI runner. It writes
`.i18nrc.json`, `.i18n/context/project.md`, and local artifact rules in `.gitignore`.

Example configuration:

```json
{
    "platform": "ios",
    "sourceLocale": "en-GB",
    "sourceFile": "PocketFleet/Supporting Files/en-GB.lproj/Localizable.strings",
    "targetPathPattern": "PocketFleet/Supporting Files/{fileLocale}.lproj/Localizable.strings",
    "resources": {
        "table": "Localizable",
        "root": "PocketFleet/Supporting Files",
        "encoding": "utf-16be",
        "fileLocales": {
            "de-DE": "de-DE",
            "pt-BR": "pt-BR"
        }
    }
}
```

The keys of `resources.fileLocales` are the configured target locales. Values preserve the exact directory names used
on disk, including projects that use language-only directories such as `de.lproj`.

## SwiftGen

The CLI updates `.strings` resources only. Existing SwiftGen configuration and generated Swift sources remain under
the app's build process. When source keys are added, run the project's normal SwiftGen or Xcode build workflow to
regenerate its typed localization API.

## Phrase migration

Preview and remove the obsolete root-level Phrase configuration after the new workflow has been verified:

```sh
npx @rio-cloud/i18n cleanup-phrase --dry-run
npx @rio-cloud/i18n cleanup-phrase
```

The cleanup intentionally does not recursively remove nested Phrase configurations. A separate configuration such as
`fastlane/.phraseapp.yml` may belong to another localization workflow, for example App Store release notes, and must be
reviewed independently.