Reusable coding agent skill and shell helper for switching an iOS Simulator’s system language and locale, rebooting it, and verifying the effective settings for localization QA.

README.md

simulator-locale

Small reusable skill and helper script for switching an iOS Simulator to a target system language and region.

It writes the simulator's global AppleLanguages and AppleLocale, reboots the simulator, waits for boot completion, and prints the effective values back for verification.

Files

• SKILL.md — agent-facing instructions for when and how to use the workflow
• set-simulator-locale.sh — shell helper that performs the locale switch and reboot

Structure

.
├── README.md
├── scripts
│   └── set-simulator-locale.sh
└── SKILL.md

Usage

Make the helper executable first:

chmod +x scripts/set-simulator-locale.sh

Run the helper with:

./scripts/set-simulator-locale.sh <simulator-target> <language-code> <locale-code>

Examples:

./scripts/set-simulator-locale.sh booted fr fr_FR
./scripts/set-simulator-locale.sh booted ja ja_JP
./scripts/set-simulator-locale.sh "iPhone Air" es es_ES

Target formats

The first argument can be:

• booted to target the currently booted simulator
• a simulator UDID
• a simulator device name, such as iPhone Air

Notes

• This changes the simulator's system-wide locale, not per-app launch arguments.
• After switching locale, launch the app again if you want to verify localized UI behavior.
• Useful for localization QA, screenshot generation, and widget/runtime sanity checks across supported locales.

set-simulator-locale.sh

#!/bin/zsh

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  set-simulator-locale.sh <simulator-target> <language-code> <locale-code>

Examples:
  set-simulator-locale.sh booted fr fr_FR
  set-simulator-locale.sh 0AD1520E-77E3-4E04-B885-995D08D3F96B ja ja_JP
EOF
}

if [[ $# -ne 3 ]]; then
  usage
  exit 1
fi

target="$1"
language_code="$2"
locale_code="$3"

resolve_udid() {
  local raw_target="$1"

  if [[ "$raw_target" == "booted" ]]; then
    xcrun simctl list devices | awk -F '[()]' '/Booted/{print $2; exit}'
    return
  fi

  if [[ "$raw_target" =~ ^[0-9A-Fa-f-]{36}$ ]]; then
    printf '%s\n' "$raw_target"
    return
  fi

  xcrun simctl list devices available | awk -v name="$raw_target" -F '[()]' '
    $0 ~ name" \\(" && $0 !~ /unavailable/ { print $2; exit }
  '
}

udid="$(resolve_udid "$target")"

if [[ -z "${udid:-}" ]]; then
  echo "Could not resolve simulator target: $target" >&2
  exit 1
fi

echo "Setting simulator $udid to language=$language_code locale=$locale_code"

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" >/dev/null 2>&1 || true
xcrun simctl boot "$udid"
xcrun simctl bootstatus "$udid" -b

echo "AppleLanguages:"
xcrun simctl spawn "$udid" defaults read NSGlobalDomain AppleLanguages
echo
echo "AppleLocale:"
xcrun simctl spawn "$udid" defaults read NSGlobalDomain AppleLocale

SKILL.md

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:

xcrun simctl list devices
xcrun simctl list devices | grep Booted

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

booted

as the simulator target for the bundled script.

Step 2: Use the bundled helper

Run:

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

Examples:

/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:

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:

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:

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.