@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/ios-localization/SKILL.md

@@ -1,473 +1,360 @@
 ---
 name: ios-localization
-description: "Implement, review, or improve localization and internationalization in iOS/macOS apps  -  String Catalogs (.xcstrings), generated localizable symbols, stable key naming, LocalizedStringKey, LocalizedStringResource, pluralization, FormatStyle for numbers/dates/measurements, right-to-left layout, Dynamic Type, and locale-aware formatting. Use when adding multi-language support, setting up String Catalogs, enabling generated symbols for compile-time-safe localization keys, handling plural forms, formatting dates/numbers/currencies for different locales, testing localizations, or making UI work correctly in RTL languages like Arabic and Hebrew."
+description: "i18n and l10n for iOS and macOS: String Catalogs (.xcstrings), generated localizable symbols with compile-time-checked keys, stable key naming, LocalizedStringKey, LocalizedStringResource, String(localized:), plurals, device variations, locale-aware FormatStyle for numbers, dates, currency and measurements, right-to-left layout, Dynamic Type, localization testing. Use when implementing or reviewing localization, adding languages, setting up catalogs, formatting values per locale, testing translations or making UI work in Arabic or Hebrew. Not for custom or parseable FormatStyle, parsing, interval or URL format styles (swift-formatstyle)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# iOS Localization & Internationalization
+# iOS Localization
 
-Localize iOS 26+ apps using String Catalogs, modern string types, FormatStyle, and RTL-aware layout. Localization mistakes cause App Store rejections in non-English markets, mistranslated UI, and broken layouts. Ship with correct localization from the start.
+This skill targets iOS 26+ apps built with String Catalogs, the modern Swift
+string types, `FormatStyle` and layout that respects writing direction. Each API
+below keeps its own, often much older, availability.
 
-## Contents
+Retrofitting localization late is expensive. Hard-coded copy, glued-together
+sentences and fixed widths show up as rejected builds in non-English
+storefronts, mistranslated screens and clipped layouts. Treat every visible
+string and every formatted value as localizable from the first commit.
 
-- [String Catalogs (.xcstrings)](#string-catalogs-xcstrings)
-- [String Catalogs (Xcode 15+) and Generated Symbols (Xcode 26+)](#string-catalogs-xcode-15-and-generated-symbols-xcode-26)
-- [String Types -- Decision Guide](#string-types-decision-guide)
-- [String Interpolation in Localized Strings](#string-interpolation-in-localized-strings)
-- [Pluralization](#pluralization)
-- [FormatStyle -- Locale-Aware Formatting](#formatstyle-locale-aware-formatting)
-- [Right-to-Left (RTL) Layout](#right-to-left-rtl-layout)
-- [Common Mistakes](#common-mistakes)
-- [Localization Review Checklist](#review-checklist)
-- [References](#references)
+Deep material lives in two references:
 
-## String Catalogs (.xcstrings)
+- [references/string-catalogs.md](references/string-catalogs.md): catalog
+  creation, extraction rules, key management, bundles and Swift packages,
+  plurals, device variants, translator export and import, the JSON format,
+  generated symbols, testing and migration.
+- [references/formatstyle-locale.md](references/formatstyle-locale.md):
+  locale-aware formatting for every value type, legacy formatter migration, RTL
+  in depth, `@ScaledMetric` and layout checks with Accessibility Inspector.
 
-String Catalogs are the recommended Xcode 15+ workflow for new localization work. They keep localizable strings, pluralization rules, and device variations together in an Xcode-managed JSON file with a visual editor. Legacy `.strings` and `.stringsdict` files can coexist during migration, but new Swift and SwiftUI code should default to String Catalogs.
+## String Catalogs
 
-**Why String Catalogs exist:**
-- `.strings` files required manual key management and fell out of sync
-- `.stringsdict` required complex XML for plurals
-- String Catalogs auto-extract strings from code, track translation state, and support plurals natively
+A String Catalog is a JSON file managed by Xcode, edited through a visual
+table, that keeps source strings, translations, plural forms and per-device
+variants in one place. Catalogs have been the recommended way to localize
+since Xcode 15. Legacy `.strings` and `.stringsdict` files can live next to a
+catalog while a project migrates, but new Swift and SwiftUI code should start
+in a catalog.
 
-**How automatic extraction works:**
+Why the switch: `.strings` files needed hand-maintained keys that silently
+drifted from the code, and `.stringsdict` plural rules were long XML
+dictionaries. A catalog is filled in by the build, tracks the state of each
+translation, and models plurals directly.
 
-Xcode scans for these patterns on each build:
+Every build, Xcode scans the source for known localizable call patterns and
+adds any key it finds. Keys then show a state in the editor such as Needs
+Review, Translated or Stale.
 
 ```swift
-// SwiftUI -- automatically extracted (LocalizedStringKey)
-Text("Welcome back")              // key: "Welcome back"
-Label("Settings", systemImage: "gear")
-Button("Save") { }
-Toggle("Dark Mode", isOn: $dark)
-
-// Programmatic -- automatically extracted
-String(localized: "No items found")
-LocalizedStringResource("Order placed")
-
-// NOT extracted -- plain String, not localized
-let msg = "Hello"                 // just a String, invisible to Xcode
-```
-
-Xcode adds discovered keys to the String Catalog automatically. Mark translations as Needs Review, Translated, or Stale in the editor.
+struct TripHeader: View {
+    @State private var alertsOn = true
+
+    var body: some View {
+        VStack {
+            Text("Your upcoming trips")                           // extracted
+            Label("Boarding pass", systemImage: "ticket")       // extracted
+            Button("Check in") { }                               // extracted
+            Toggle("Gate alerts", isOn: $alertsOn)               // extracted
+        }
+    }
+}
 
-For detailed String Catalog workflows, migration, and testing strategies, see [references/string-catalogs.md](references/string-catalogs.md).
+let banner = String(localized: "Seat changed")                   // extracted
+let hint = LocalizedStringResource("Arrive two hours early")     // extracted
+let debugTag = "trip-header"   // plain String: never extracted, never translated
+```
 
-## String Catalogs (Xcode 15+) and Generated Symbols (Xcode 26+)
+For a SwiftUI initializer the literal itself becomes the key.
 
-For generated-symbol or migration answers, start by stating: "String Catalogs are the recommended Xcode 15+ localization workflow. Xcode 26 generated symbols are a separate typed-access layer on top of String Catalogs." Then explain generated symbols, plurals, or migration details. Do not describe catalogs themselves as requiring Xcode 26 or iOS 17.
+## Generated Symbols (Xcode 26) on Top of Catalogs
 
-**Enable:** Build Settings > Localization > Generate String Catalog Symbols → `Yes` (on by default in new Xcode 26 projects). Requires catalog format version `1.1`.
+When a question is about generated symbols or about migrating to them, say
+this first: catalogs are the Xcode 15+ workflow, and generated symbols are a
+separate typed-access layer that Xcode 26 builds on those catalogs. Do not say
+catalogs require Xcode 26, and do not tie them to iOS 17.
 
-**Workflow:** Add a key manually via the (+) button in the String Catalog editor  -  manual keys have the **Generate Swift Symbol** checkbox enabled by default. Auto-extracted keys can also opt in via Refactor > Convert Strings to Symbols. Use stable manual keys for generated-symbol strings. Avoid source-copy-derived keys for API-facing strings because wording edits can rename generated identifiers and churn call sites.
+- Turn it on with Build Settings > Localization > Generate String Catalog
+  Symbols = `Yes`. New Xcode 26 projects already have it on.
+- The catalog must use format version `1.1`.
+- A key added by hand with the (+) button has Generate Swift Symbol ticked by
+  default. Keys that came from extraction opt in through Refactor > Convert
+  Strings to Symbols, which can be undone later.
+- Pick stable, hand-written keys for anything reached through a symbol. A key
+  derived from the English copy renames its symbol the moment someone edits
+  the wording, and every call site churns.
 
 ```swift
-// Generated from key "item_available" in Localizable.xcstrings
-Text(.itemAvailable)
+// Localizable.xcstrings: "cart_empty" -> "Your cart is empty"
+Text(.cartEmpty)
 
-// Parameterized key "products_count" with %1$(count)lld
-Text(.productsCount(count: 42))
+// "seats_left" -> "%1$(remaining)lld seats left"
+Text(.seatsLeft(remaining: 3))
 
-// Non-default table "Checkout.xcstrings"
-Text(.Checkout.confirmOrderCta)
+// Separate table Payments.xcstrings, key "apply_voucher_cta"
+Text(.Payments.applyVoucherCta)
 ```
 
-Xcode derives symbol names by camelCasing the key: `settings.notifications.toggle` → `.settingsNotificationsToggle`. You can convert existing extracted strings to symbols via Refactor > Convert Strings to Symbols (reversible).
+Symbols are the key in camelCase: `profile.privacy.header` becomes
+`.profilePrivacyHeader`. They are generated with `internal` access, so another
+module needs a small public wrapper. When wrappers pile up across many modules,
+the open-source `xcstrings-tool` package plugin generates public accessors.
 
-Generated symbols are `internal`. For cross-module access, create a public wrapper extension. For heavier multi-module setups, use [xcstrings-tool](https://github.com/liamnichols/xcstrings-tool) instead.
+## Picking a String Type
 
-For the full generated symbols reference  -  extraction states, symbol derivation rules, and cross-module patterns  -  see [references/string-catalogs.md](references/string-catalogs.md).
+### LocalizedStringKey
 
-## String Types -- Decision Guide
-
-### LocalizedStringKey (SwiftUI default)
-
-SwiftUI views accept `LocalizedStringKey` for their text parameters. String literals are implicitly converted -- no extra work needed.
+Text parameters of SwiftUI views are `LocalizedStringKey`, and a string literal
+converts to it implicitly, so lookup just happens:
 
 ```swift
-// These all create a LocalizedStringKey lookup automatically:
-Text("Welcome back")
-Label("Profile", systemImage: "person")
-Button("Delete") { deleteItem() }
-.navigationTitle("Home")
+NavigationStack {
+    List {
+        Label("Saved places", systemImage: "mappin")
+        Button("Clear history") { }
+    }
+    .navigationTitle("Places")
+}
 ```
 
-Use `LocalizedStringKey` when passing strings directly to SwiftUI view initializers. Do not construct `LocalizedStringKey` manually in most cases.
+Pass literals straight into SwiftUI initializers. Building a
+`LocalizedStringKey` by hand is rarely needed.
 
-### String(localized:) -- Modern NSLocalizedString replacement
+### String(localized:)
 
-Use for any localized string outside a SwiftUI view initializer. Returns a plain `String`. The literal/interpolated initializer is available iOS 15+; resolving a `LocalizedStringResource` is iOS 16+.
+`String(localized:)` replaces `NSLocalizedString`. It returns a resolved
+`String` for code that is not a SwiftUI initializer argument. The literal and
+interpolation form needs iOS 15; resolving a `LocalizedStringResource` needs
+iOS 16.
 
 ```swift
-// Basic
-let title = String(localized: "Welcome back")
+let title = String(localized: "Refund requested")
+let note = String(localized: "refund.pending.note",
+                  defaultValue: "Refunds take up to 5 business days")
+let label = String(localized: "Download", table: "Offline", bundle: .module)
+let verb = String(localized: "Book",
+                  comment: "Verb on a button that reserves a table")
+```
 
-// With default value (key differs from English text)
-let msg = String(localized: "error.network",
-                 defaultValue: "Check your internet connection")
+A Swift package that still shows English falls into one of three setup gaps.
+Check them in order before touching bundle lookup:
 
-// With table and bundle
-let label = String(localized: "onboarding.title",
-                   table: "Onboarding",
-                   bundle: .module)
+1. `Package.swift` sets `defaultLocalization`.
+2. The target's `resources` processes the folder that holds the catalog, for
+   example `.process("Resources")`.
+3. `Localizable.xcstrings` really sits inside that processed folder.
 
-// With comment for translators
-let btn = String(localized: "Save",
-                 comment: "Button title to save the current document")
-```
+Only once all three hold, debug lookup with `bundle: .module` in
+`String(localized:)` and `Text(_:bundle:)`.
 
-For Swift package localization failures, answer with this explicit resource checklist before bundle debugging:
-1. `Package.swift` declares `defaultLocalization`.
-2. The target `resources` list processes the catalog location, such as `.process("Resources")`.
-3. `Localizable.xcstrings` is actually inside that processed target-resource path.
-Only after those pass, debug lookup with `bundle: .module` or `Text(..., bundle: .module)`.
+Xcode can still export and migrate literal-key `NSLocalizedString` calls, but
+new code uses `String(localized:)`, SwiftUI literals,
+`LocalizedStringResource` or generated symbols.
 
-Existing `NSLocalizedString` literal keys can still be exported or migrated by Xcode tooling, but new Swift code should prefer `String(localized:)`, SwiftUI literals, `LocalizedStringResource`, or generated symbols.
+### LocalizedStringResource
 
-### LocalizedStringResource -- Pass localization info without resolving
-
-Use when a string must be carried as a localizable value for later resolution, especially for App Intents, widgets, notifications, generated localizable symbols, and system APIs that accept `LocalizedStringResource` directly. Use `String(localized:)` when code needs the resolved string immediately. Available iOS 16+.
+`LocalizedStringResource` (iOS 16+) carries a localizable value that someone
+else resolves later: App Intents, widgets, notifications, generated symbols
+and system APIs that accept it. When you need the text now, use
+`String(localized:)`.
 
 ```swift
-// App Intents require LocalizedStringResource
-struct OrderCoffeeIntent: AppIntent {
-    static var title: LocalizedStringResource = "Order Coffee"
+struct StartTimerIntent: AppIntent {
+    static let title: LocalizedStringResource = "Start Focus Timer"
+    func perform() async throws -> some IntentResult { .result() }
 }
 
-// Widgets
-struct MyWidget: Widget {
+struct StepsWidget: Widget {
     var body: some WidgetConfiguration {
-        StaticConfiguration(kind: "timer",
-                            provider: Provider()) { entry in
-            TimerView(entry: entry)
+        StaticConfiguration(kind: "steps", provider: StepsProvider()) { entry in
+            StepsView(entry: entry)
         }
-        .configurationDisplayName(LocalizedStringResource("Timer"))
+        .configurationDisplayName(LocalizedStringResource("Daily Steps"))
     }
 }
 
-// Pass around without resolving yet
-func showAlert(title: LocalizedStringResource, message: LocalizedStringResource) {
-    // Resolved at display time with the user's current locale
-    let resolved = String(localized: title)
+func showToast(_ message: LocalizedStringResource) {
+    let text = String(localized: message)   // resolved in the current locale
+    toastCenter.present(text)
 }
 ```
 
-### When to use each type
+### Which type where
 
 | Context | Type | Why |
-|---------|------|-----|
-| SwiftUI view text parameters | `LocalizedStringKey` (implicit) | SwiftUI handles lookup automatically |
-| Computed strings in view models / services | `String(localized:)` | Returns resolved `String` for logic |
-| App Intents, widgets, system APIs | `LocalizedStringResource` | Framework resolves at display time |
-| Error messages shown to users | `String(localized:)` | Resolved in catch blocks |
-| Logging / analytics (not user-facing) | Plain `String` | No localization needed |
-
-## String Interpolation in Localized Strings
-
-Interpolated values in localized strings become positional arguments that translators can reorder.
+|---|---|---|
+| SwiftUI view text parameters | `LocalizedStringKey` (implicit) | SwiftUI does the lookup |
+| Strings built in view models or services | `String(localized:)` | Logic needs the resolved value |
+| App Intents, widgets, system APIs | `LocalizedStringResource` | The framework resolves at display time |
+| Error text shown to the user | `String(localized:)` | Resolved inside the `catch` |
+| Logs and analytics | `String` | Never shown to users |
 
-```swift
-// English: "Welcome, Alice! You have 3 new messages."
-// German:  "Willkommen, Alice! Sie haben 3 neue Nachrichten."
-// Japanese: "Alice さん、新しいメッセージが 3 件あります。"
-let text = String(localized: "Welcome, \(name)! You have \(count) new messages.")
-```
+## Interpolation
 
-In the String Catalog, this appears with `%@` and `%lld` placeholders that translators can reorder:
-- English: `"Welcome, %@! You have %lld new messages."`
-- Japanese: `"%@さん、新しいメッセージが%lld件あります。"`
+Interpolated values become positional arguments, so a translator can move them
+around the sentence:
 
-**Type-safe interpolation** (preferred over format specifiers):
 ```swift
-// Interpolation provides type safety
-String(localized: "Score: \(score, format: .number)")
-String(localized: "Due: \(date, format: .dateTime.month().day())")
+let summary = String(localized: "\(guestName) booked \(nights) nights")
+// Catalog key: "%@ booked %lld nights"
+// Japanese can place the arguments in its own order.
 ```
 
-## Pluralization
-
-String Catalogs handle pluralization natively -- no `.stringsdict` XML required.
+Give interpolations a format instead of raw specifiers:
+`\(distance, format: .number)` or `\(departure, format: .dateTime.hour().minute())`.
 
-### Setup in String Catalog
+## Plurals
 
-When a localized string contains an integer interpolation, Xcode detects it and offers plural variants in the String Catalog editor. Supply translations for each CLDR plural category:
-
-| Category | English example | Arabic example |
-|----------|----------------|----------------|
-| zero | (not used) | 0 items |
-| one | 1 item | 1 item |
-| two | (not used) | 2 items (dual) |
-| few | (not used) | 3-10 items |
-| many | (not used) | 11-99 items |
-| other | 2+ items | 100+ items |
-
-English uses only `one` and `other`. Arabic uses all six. Always supply `other` as the fallback.
+Catalogs model plurals directly; no `.stringsdict`. Interpolate an integer,
+build, and the editor offers plural variants for that key. CLDR defines six
+categories: zero, one, two, few, many, other. English only uses one and other.
+Arabic uses all six: zero, one, two (dual), few (3 to 10), many (11 to 99) and
+other (100 and up). Always fill `other`; it is the fallback.
 
 ```swift
-// Code -- single interpolation triggers plural support
-Text("\(unreadCount) unread messages")
-
-// String Catalog entries (English):
-//   one:   "%lld unread message"
-//   other: "%lld unread messages"
+Text("\(pendingInvites) pending invites")
+// en one:   "%lld pending invite"
+// en other: "%lld pending invites"
 ```
 
-### Device Variations
+### Device variations
 
-String Catalogs support device-specific text (iPhone vs iPad vs Mac):
+Vary by Device lets one key read differently per device, for instance "Tap to
+edit" on iPhone, "Tap or click to edit" on iPad and "Click to edit" on Mac.
 
-```swift
-// In String Catalog editor, enable "Vary by Device" for a key
-// iPhone: "Tap to continue"
-// iPad:   "Tap or click to continue"
-// Mac:    "Click to continue"
-```
+### Grammar agreement (iOS 15+)
 
-### Grammar Agreement (iOS 15+)
-
-Use `^[...]` inflection syntax for automatic grammatical agreement:
-
-```swift
-// Automatically adjusts for gender/number in supported languages
-Text("^[\(count) \("photo")](inflect: true) added")
-// English: "1 photo added" / "3 photos added"
-// Spanish: "1 foto agregada" / "3 fotos agregadas"
-```
-
-## FormatStyle -- Locale-Aware Formatting
-
-Never hard-code date, number, or measurement formats. Use `FormatStyle` (iOS 15+) so formatting adapts to the user's locale automatically.
-
-Locale-aware formatting matters even in single-language apps because user locale affects separators, calendars, currency, units, names, and list formatting. When giving user-facing formatting advice, explicitly recommend testing or previewing output under multiple locales such as `en_US`, `de_DE`, `ar_SA`, and `ja_JP`.
-
-`ios-localization` owns `FormatStyle` guidance when the issue is locale-aware user-facing display, including numbers, dates, currency, units, names, lists, calendars, separators, and locale preview/testing. For custom `FormatStyle`, `ParseableFormatStyle`, parsing, `Date.IntervalFormatStyle`, `URL.FormatStyle`, or reusable formatter API design, route to `swift-formatstyle`; keep `ios-localization` advice to locale risks and testing unless implementation is explicitly requested.
-
-### Dates
-
-```swift
-let now = Date.now
-
-// Preset styles
-now.formatted(date: .long, time: .shortened)
-// US: "January 15, 2026 at 3:30 PM"
-// DE: "15. Januar 2026 um 15:30"
-// JP: "2026年1月15日 15:30"
-
-// Component-based
-now.formatted(.dateTime.month(.wide).day().year())
-// US: "January 15, 2026"
-
-// In SwiftUI
-Text(now, format: .dateTime.month().day().year())
-```
-
-### Numbers
+Automatic grammar agreement fixes gender and number for supported languages
+with the inflection markup `^[...](inflect: true)`:
 
 ```swift
-let count = 1234567
-count.formatted()                     // "1,234,567" (US) / "1.234.567" (DE)
-count.formatted(.number.precision(.fractionLength(2)))
-count.formatted(.percent)             // For 0.85 -> "85%" (US) / "85 %" (FR)
-
-// Currency
-let price = Decimal(29.99)
-price.formatted(.currency(code: "USD"))  // "$29.99" (US) / "29,99 $US" (FR)
-price.formatted(.currency(code: "EUR"))  // "29,99 EUR" (DE)
+Text("Added ^[\(bottleCount) bottle](inflect: true) to your cellar")
+// English: 1 bottle / 3 bottles; Spanish forms agree automatically.
 ```
 
-### Measurements
+## Locale-Aware Formatting with FormatStyle
 
-```swift
-let distance = Measurement(value: 5, unit: UnitLength.kilometers)
-distance.formatted(.measurement(width: .wide))
-// US: "3.1 miles" (auto-converts!) / DE: "5 Kilometer"
+Never hard-code date, number or measurement patterns; use `FormatStyle`
+(iOS 15+). Locale still matters in a one-language app: decimal and grouping
+separators, calendars, currency symbols, units, name order and list
+conjunctions all follow the user's region. Whenever you advise on user-facing
+formatting, also tell the reader to preview or test under several locales such
+as `en_US`, `de_DE`, `ar_SA` and `ja_JP`.
 
-let temp = Measurement(value: 22, unit: UnitTemperature.celsius)
-temp.formatted(.measurement(width: .abbreviated))
-// US: "72 F" (auto-converts!) / FR: "22 C"
-```
-
-### Duration, PersonName, Lists
+Scope boundary: this skill owns `FormatStyle` for locale-aware display
+(numbers, dates, currency, units, names, lists, calendars, separators, and
+locale previews and tests). Custom `FormatStyle` types, `ParseableFormatStyle`,
+parsing, `Date.IntervalFormatStyle`, `URL.FormatStyle` and reusable formatter
+API design belong to `swift-formatstyle`. Here, only point out locale risks and
+testing for those, unless the user explicitly asks for an implementation.
 
 ```swift
-// Duration
-let dur = Duration.seconds(3661)
-dur.formatted(.time(pattern: .hourMinuteSecond))  // "1:01:01"
-
-// Person names
-let name = PersonNameComponents(givenName: "John", familyName: "Doe")
-name.formatted(.name(style: .long))   // "John Doe" (US) / "Doe John" (JP)
-
-// Lists
-let items = ["Apples", "Oranges", "Bananas"]
-items.formatted(.list(type: .and))    // "Apples, Oranges, and Bananas" (EN)
-                                      // "Apples, Oranges et Bananas" (FR)
+let flight = Date.now
+flight.formatted(date: .long, time: .shortened)
+// en_US "June 3, 2026 at 4:05 PM", de_DE "3. Juni 2026 um 16:05"; ja_JP uses year-month-day order
+flight.formatted(.dateTime.month(.wide).day().year())
+Text(flight, format: .dateTime.weekday().hour().minute())
+
+let visitors = 1_284_503
+visitors.formatted()                                    // "1,284,503" / "1.284.503"
+3.14159.formatted(.number.precision(.fractionLength(2)))
+0.18.formatted(.percent)                                 // "18%"
+Decimal(59.9).formatted(.currency(code: "USD"))
+Decimal(59.9).formatted(.currency(code: "EUR"))          // symbol position follows locale
+
+Measurement(value: 42, unit: UnitLength.kilometers)
+    .formatted(.measurement(width: .wide))               // miles in en_US
+Measurement(value: 21, unit: UnitTemperature.celsius)
+    .formatted(.measurement(width: .abbreviated))        // Fahrenheit in en_US
+
+Duration.seconds(5_025).formatted(.time(pattern: .hourMinuteSecond))   // "1:23:45"
+var author = PersonNameComponents(); author.givenName = "Aiko"; author.familyName = "Tanaka"
+author.formatted(.name(style: .long))                    // order differs en_US vs ja_JP
+["tea", "coffee", "juice"].formatted(.list(type: .and))  // "tea, coffee, and juice"; French joins with "et" and no serial comma
 ```
 
-For the complete FormatStyle reference, custom styles, and RTL layout, see [references/formatstyle-locale.md](references/formatstyle-locale.md).
-
-## Right-to-Left (RTL) Layout
-
-SwiftUI automatically mirrors layouts for RTL languages (Arabic, Hebrew, Urdu, Persian). Most views require zero changes.
-
-### What SwiftUI auto-mirrors
+Full coverage of every style is in
+[references/formatstyle-locale.md](references/formatstyle-locale.md).
 
-- `HStack` children reverse order
-- `.leading` / `.trailing` alignment and padding swap sides
-- `NavigationStack` back button moves to trailing edge
-- `List` disclosure indicators flip
-- Text alignment follows reading direction
+## Right-to-Left Layout
 
-### What needs manual attention
+SwiftUI mirrors layout for Arabic, Hebrew, Urdu and Persian on its own; most
+views need nothing. It flips `HStack` order, `.leading` and `.trailing`
+alignment and padding, puts the `NavigationStack` back button on the trailing
+side, mirrors `List` disclosure chevrons, and aligns text to the reading
+direction.
 
 ```swift
-// Testing RTL in previews
-MyView()
-    .environment(\.layoutDirection, .rightToLeft)
-    .environment(\.locale, Locale(identifier: "ar"))
+#Preview("Checkout, Arabic") {
+    CheckoutView()
+        .environment(\.layoutDirection, .rightToLeft)
+        .environment(\.locale, Locale(identifier: "ar"))
+}
 
-// Images that should mirror (directional arrows, progress indicators)
-Image(systemName: "chevron.right")
+Image(systemName: "arrowshape.forward")          // directional: mirror it
     .flipsForRightToLeftLayoutDirection(true)
 
-// Images that should NOT mirror: logos, photos, clocks, music notes
-
-// Forced LTR for specific content (phone numbers, code)
-Text("+1 (555) 123-4567")
+Text(verbatim: supportHotline)                    // phone numbers and code stay LTR
     .environment(\.layoutDirection, .leftToRight)
 ```
 
-### Layout rules
+Leave logos, photos, clocks and musical notation unmirrored.
 
-- **DO** use `.leading` / `.trailing` -- they auto-flip for RTL
-- **DON'T** use `.left` / `.right` -- they are fixed and break RTL
-- **DO** use `HStack` / `VStack` -- they respect layout direction
-- **DON'T** use absolute `offset(x:)` for directional positioning
+Rules: prefer `.leading` and `.trailing` (they flip) over `.left` and `.right`
+(they do not); build with `HStack` and `VStack`; do not use absolute
+`offset(x:)` to place things in a direction.
 
 ## Common Mistakes
 
-### DON'T: Use NSLocalizedString in new Swift code
-```swift
-// LEGACY -- Xcode can export literal keys, but new Swift code should use modern APIs
-let title = NSLocalizedString("welcome_title", comment: "Welcome screen title")
-```
-
-### DO: Use String(localized:) or let SwiftUI handle it
-```swift
-// CORRECT
-let title = String(localized: "welcome_title",
-                   defaultValue: "Welcome!",
-                   comment: "Welcome screen title")
-// Or in SwiftUI, just:
-Text("Welcome!")
-```
-
-### DON'T: Concatenate localized strings
-```swift
-// WRONG -- word order varies by language
-let greeting = String(localized: "Hello") + ", " + name + "!"
-```
-
-### DO: Use string interpolation
-```swift
-// CORRECT -- translators can reorder placeholders
-let greeting = String(localized: "Hello, \(name)!")
-```
-
-### DON'T: Hard-code date/number formats
-```swift
-// WRONG -- US-only format
-let formatter = DateFormatter()
-formatter.dateFormat = "MM/dd/yyyy"  // Meaningless in most countries
-```
-
-### DO: Use FormatStyle
-```swift
-// CORRECT -- adapts to user locale
-Text(date, format: .dateTime.month().day().year())
-```
-
-### DON'T: Use fixed-width layouts
-```swift
-// WRONG -- German text is ~30% longer than English
-Text(title).frame(width: 120)
-```
-
-### DO: Use flexible layouts
-```swift
-// CORRECT
-Text(title).fixedSize(horizontal: false, vertical: true)
-// Or use VStack/wrapping that accommodates expansion
-```
-
-### DON'T: Use .left / .right for alignment
-```swift
-// WRONG -- does not flip for RTL
-HStack { Spacer(); text }.padding(.left, 16)
-```
-
-### DO: Use .leading / .trailing
-```swift
-// CORRECT
-HStack { Spacer(); text }.padding(.leading, 16)
-```
-
-### DON'T: Put user-facing strings as plain String outside SwiftUI
-```swift
-// WRONG -- not localized
-let errorMessage = "Something went wrong"
-showAlert(message: errorMessage)
-```
-
-### DO: Use LocalizedStringResource for deferred resolution
-```swift
-// CORRECT
-let errorMessage = LocalizedStringResource("Something went wrong")
-showAlert(message: String(localized: errorMessage))
-```
-
-### DON'T: Use natural-language text as the key for manually-managed strings
-```swift
-// WRONG -- typo silently creates a new key, stales the old one, no compiler error
-Text("Wlecome Back")  // was "Welcome Back" -- silent localization break
-```
-
-### DO: Use stable symbol-style keys and enable generated symbols
-```swift
-// CORRECT -- key is stable; UI text lives in the catalog's default value
-Text(.welcomeBack)  // generated from key "welcome_back" in String Catalog
-// Or without generated symbols:
-String(localized: "welcome_back", defaultValue: "Welcome Back")
-```
-
-### DON'T: Skip pseudolocalization testing
-Testing only in English hides truncation, layout, and RTL bugs.
-
-### DO: Test with German (long) and Arabic (RTL) at minimum
-Use Xcode scheme settings to override the app language without changing device locale.
+1. `NSLocalizedString` in new Swift code. It is legacy; use
+   `String(localized:defaultValue:comment:)` or a `Text` literal.
+2. Building a sentence from localized fragments. Word order changes between
+   languages; localize one interpolated string.
+3. `DateFormatter` with a fixed `dateFormat` such as `"MM/dd/yyyy"`. Use
+   `Text(date, format: .dateTime.month().day().year())` or another FormatStyle.
+4. Fixed widths like `.frame(width: 120)` around text. German runs roughly 30%
+   longer than English; let text wrap with
+   `.fixedSize(horizontal: false, vertical: true)` or flexible stacks.
+5. `.padding(.left, 12)`. Use `.padding(.leading, 12)`.
+6. Passing user-facing text around as `String` outside SwiftUI. Carry a
+   `LocalizedStringResource` and resolve it with `String(localized:)` where it
+   is shown.
+7. English sentences as keys for strings you manage by hand. A typo creates a
+   brand new key, the old one goes stale, and the compiler says nothing. Use
+   stable symbol-style keys, for example `order_shipped` read as
+   `Text(.orderShipped)`, or
+   `String(localized: "order_shipped", defaultValue: "Your order is on its way")`.
+8. Testing only in English. Truncation, layout and RTL bugs stay hidden;
+   run the pseudolanguages.
+9. Not testing German (long text) and Arabic (RTL) at minimum. Switch the app
+   language in the scheme options instead of changing the device locale.
 
 ## Review Checklist
 
-- [ ] All user-facing strings use localization (`LocalizedStringKey` in SwiftUI or `String(localized:)`)
-- [ ] No string concatenation for user-visible text
-- [ ] Dates and numbers use `FormatStyle`, not hardcoded formats
-- [ ] Pluralization handled via String Catalog plural variants (not manual if/else)
-- [ ] Layout uses `.leading` / `.trailing`, not `.left` / `.right`
-- [ ] UI tested with long text (German) and RTL (Arabic)
-- [ ] String Catalog includes all target languages
-- [ ] Images needing RTL mirroring use `.flipsForRightToLeftLayoutDirection(true)`
-- [ ] App Intents and widgets use `LocalizedStringResource`
-- [ ] No `NSLocalizedString` usage in new code
-- [ ] Comments provided for ambiguous keys (context for translators)
-- [ ] `@ScaledMetric` used for spacing that must scale with Dynamic Type
-- [ ] Currency formatting uses explicit currency code, not locale default
-- [ ] Pseudolocalization tested (accented, right-to-left, double-length)
-- [ ] Manually-managed keys use stable symbol-style names, not English text as the key
-- [ ] Generate String Catalog Symbols enabled for targets with manually-managed keys
-- [ ] Ensure localized string types are Sendable; use @MainActor for locale-change UI updates
+- [ ] Every user-facing string is localized (`LocalizedStringKey` or
+      `String(localized:)`)
+- [ ] No string concatenation for visible text
+- [ ] Dates and numbers go through `FormatStyle`, never fixed patterns
+- [ ] Plurals use catalog plural variants, not `if count == 1`
+- [ ] `.leading` and `.trailing` instead of `.left` and `.right`
+- [ ] UI checked with long text (German) and RTL (Arabic)
+- [ ] The catalog lists every shipping language
+- [ ] Directional images use `.flipsForRightToLeftLayoutDirection(true)`
+- [ ] App Intents and widgets take `LocalizedStringResource`
+- [ ] No `NSLocalizedString` in new code
+- [ ] Ambiguous keys carry translator comments
+- [ ] Spacing that must track Dynamic Type uses `@ScaledMetric`
+- [ ] Currency always names an explicit currency code instead of relying on the
+      locale default
+- [ ] Pseudolocalization run: accented, right-to-left, double-length
+- [ ] Hand-managed keys are stable symbol-style names, not English sentences
+- [ ] Generate String Catalog Symbols is on for targets with manual keys
+- [ ] Localized string types are `Sendable`; UI reacting to a locale change
+      updates on `@MainActor`
 
 ## References
 
-- FormatStyle patterns: [references/formatstyle-locale.md](references/formatstyle-locale.md)
-- String Catalogs guide: [references/string-catalogs.md](references/string-catalogs.md)
+- [references/string-catalogs.md](references/string-catalogs.md): catalogs,
+  keys, bundles, packages, plurals, translator workflow, JSON, symbols,
+  testing and migration.
+- [references/formatstyle-locale.md](references/formatstyle-locale.md):
+  FormatStyle per value type, forcing a locale, RTL, `@ScaledMetric` and
+  Accessibility Inspector.