---
name: simulator-locale
description: Switch an iOS Simulator to a different system language and region for localization QA. Use when asked to change the simulator language, reboot a simulator into another locale, verify AppleLanguages or AppleLocale, or prepare a simulator for localized screenshots or runtime checks.
---

## Step 1: Resolve the target simulator

Prefer a concrete UDID.

Useful commands:

```bash
xcrun simctl list devices
xcrun simctl list devices | grep Booted
```

If the user refers to the currently booted simulator, you can use:

```bash
booted
```

as the simulator target for the bundled script.

## Step 2: Use the bundled helper

Run:

```bash
/Users/sbm/.agents/skills/simulator-locale/scripts/set-simulator-locale.sh <SIMULATOR_TARGET> <LANGUAGE_CODE> <LOCALE_CODE>
```

Examples:

```bash
/Users/sbm/.agents/skills/simulator-locale/scripts/set-simulator-locale.sh booted fr fr_FR
/Users/sbm/.agents/skills/simulator-locale/scripts/set-simulator-locale.sh 0AD1520E-77E3-4E04-B885-995D08D3F96B ja ja_JP
```

## Step 3: Understand what the helper does

The helper:

1. Resolves the simulator target.
2. Writes `AppleLanguages` in `NSGlobalDomain`.
3. Writes `AppleLocale` in `NSGlobalDomain`.
4. Shuts the simulator down.
5. Boots it again.
6. Waits for boot completion.
7. Prints the effective language and locale values.

This is intended for system-wide simulator locale changes, not per-app launch arguments.

## Step 4: Manual fallback

If you need to run the raw commands directly:

```bash
xcrun simctl spawn <UDID> defaults write NSGlobalDomain AppleLanguages -array <LANGUAGE_CODE>
xcrun simctl spawn <UDID> defaults write NSGlobalDomain AppleLocale -string <LOCALE_CODE>
xcrun simctl shutdown <UDID>
xcrun simctl boot <UDID>
xcrun simctl bootstatus <UDID> -b
xcrun simctl spawn <UDID> defaults read NSGlobalDomain AppleLanguages
xcrun simctl spawn <UDID> defaults read NSGlobalDomain AppleLocale
```

Examples:

```bash
xcrun simctl spawn 0AD1520E-77E3-4E04-B885-995D08D3F96B defaults write NSGlobalDomain AppleLanguages -array fr
xcrun simctl spawn 0AD1520E-77E3-4E04-B885-995D08D3F96B defaults write NSGlobalDomain AppleLocale -string fr_FR
xcrun simctl shutdown 0AD1520E-77E3-4E04-B885-995D08D3F96B
xcrun simctl boot 0AD1520E-77E3-4E04-B885-995D08D3F96B
```

## Step 5: Validation

After switching locale, verify the simulator state before concluding:

```bash
xcrun simctl spawn <UDID> defaults read NSGlobalDomain AppleLanguages
xcrun simctl spawn <UDID> defaults read NSGlobalDomain AppleLocale
```

When the user cares about app behavior, separately launch the app and inspect the actual UI. The simulator being set to a locale does not guarantee the app picked it up in the current process state.