# Kotlin Multiplatform guide

The KMP platform supports AI-assisted translation of simple Compose Multiplatform string resources. It follows the
official Compose resource layout documented by JetBrains:

```text
commonMain/composeResources/
├── values/
│   └── strings.xml
├── values-de-rDE/
│   └── strings.xml
└── values-b+zh+Hans/
    └── strings.xml
```

See the official documentation for [localizing Compose Multiplatform strings](https://kotlinlang.org/docs/multiplatform/compose-localize-strings.html)
and [resource qualifiers](https://kotlinlang.org/docs/multiplatform/compose-multiplatform-resources-setup.html#qualifiers).

## Initial scope

The first KMP version supports:

- the default `composeResources/values/strings.xml` source resource
- one matching `strings.xml` file per locale-qualified `values-*` directory
- simple `<string name="…">…</string>` entries
- `translate`, `retranslate`, `improve`, and `validate`
- source-locale improvement with `improve --include-source-locale`
- `cleanup-phrase`, `test-catalog-connection`, and `test-ai-connection`
- Compose string templates such as `%1$s` and `%2$d`
- XML entities and Compose escapes such as `\n`, `\t`, and `\uXXXX`

It intentionally does not yet support plurals, string arrays, nested XML markup, several XML files per locale,
theme-qualified string resources, custom Compose resource directories, unused-key removal, key harmonization,
shared-message synchronization, or UI component inspection. Unsupported XML resources remain untouched.

## Initialize a project

Run the platform-aware setup from the KMP repository:

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

Projects containing `commonMain/composeResources/values/strings.xml` are detected as Kotlin Multiplatform projects.
To bypass detection:

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

Initialization discovers the default source resource and its locale-qualified siblings. Since the default `values`
directory does not encode a locale, the source locale defaults to `en-GB` and can be changed during setup or with
`--source-locale`.

Example configuration:

```json
{
    "platform": "kmp",
    "sourceLocale": "en-GB",
    "sourceFile": "composeApp/src/commonMain/composeResources/values/strings.xml",
    "targetPathPattern": "composeApp/src/commonMain/composeResources/values-{fileLocale}/strings.xml",
    "resources": {
        "format": "compose-xml",
        "root": "composeApp/src/commonMain/composeResources",
        "fileLocales": {
            "de-DE": "de-rDE",
            "zh-Hans": "b+zh+Hans"
        }
    }
}
```

The keys of `resources.fileLocales` are the BCP-47 locales used by i18n-flow. Their values preserve Compose's exact
directory qualifiers. Language-only directories such as `values-fr` map to `fr`; region-qualified directories such as
`values-pt-rBR` map to `pt-BR`; qualifiers with scripts use Compose's `b+` notation.

## Generated accessors

i18n-flow updates `strings.xml` only. Compose Multiplatform generates its typed `Res.string` accessors during the
normal Gradle build or IDE import, so no generated Kotlin sources are modified by the CLI.

## Phrase migration

After the new workflow has been verified, preview and remove an obsolete root-level Phrase configuration:

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