@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

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

@@ -1,6 +1,6 @@
 ---
 name: ios-localization
-description: "Implement, review, or improve localization and internationalization in iOS/macOS apps — String Catalogs (.xcstrings), 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, 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: "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."
 ---
 
 # iOS Localization & Internationalization
@@ -10,18 +10,19 @@ Localize iOS 26+ apps using String Catalogs, modern string types, FormatStyle, a
 ## Contents
 
 - [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](#localization-review-checklist)
+- [Localization Review Checklist](#review-checklist)
 - [References](#references)
 
 ## String Catalogs (.xcstrings)
 
-String Catalogs replaced `.strings` and `.stringsdict` files starting in Xcode 15 / iOS 17. They unify all localizable strings, pluralization rules, and device variations into a single JSON-based file with a visual editor.
+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.
 
 **Why String Catalogs exist:**
 - `.strings` files required manual key management and fell out of sync
@@ -49,7 +50,32 @@ 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.
 
-For detailed String Catalog workflows, migration, and testing strategies, see `references/string-catalogs.md`.
+For detailed String Catalog workflows, migration, and testing strategies, see [references/string-catalogs.md](references/string-catalogs.md).
+
+## String Catalogs (Xcode 15+) and Generated Symbols (Xcode 26+)
+
+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.
+
+**Enable:** Build Settings > Localization > Generate String Catalog Symbols → `Yes` (on by default in new Xcode 26 projects). Requires catalog format version `1.1`.
+
+**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.
+
+```swift
+// Generated from key "room_available" in Localizable.xcstrings
+Text(.roomAvailable)
+
+// Parameterized key "landmarks_count" with %1$(count)lld
+Text(.landmarksCount(count: 42))
+
+// Non-default table "Booking.xcstrings"
+Text(.Booking.confirmBookingCta)
+```
+
+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).
+
+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.
+
+For the full generated symbols reference  -  extraction states, symbol derivation rules, and cross-module patterns  -  see [references/string-catalogs.md](references/string-catalogs.md).
 
 ## String Types -- Decision Guide
 
@@ -62,14 +88,14 @@ SwiftUI views accept `LocalizedStringKey` for their text parameters. String lite
 Text("Welcome back")
 Label("Profile", systemImage: "person")
 Button("Delete") { deleteItem() }
-NavigationTitle("Home")
+.navigationTitle("Home")
 ```
 
 Use `LocalizedStringKey` when passing strings directly to SwiftUI view initializers. Do not construct `LocalizedStringKey` manually in most cases.
 
 ### String(localized:) -- Modern NSLocalizedString replacement
 
-Use for any localized string outside a SwiftUI view initializer. Returns a plain `String`. Available iOS 16+.
+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+.
 
 ```swift
 // Basic
@@ -89,9 +115,17 @@ let btn = String(localized: "Save",
                  comment: "Button title to save the current document")
 ```
 
+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)`.
+
+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 -- Pass localization info without resolving
 
-Use when you need to pass a localized string to an API that resolves it later (App Intents, widgets, notifications, system frameworks). Available iOS 16+.
+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+.
 
 ```swift
 // App Intents require LocalizedStringResource
@@ -188,7 +222,7 @@ String Catalogs support device-specific text (iPhone vs iPad vs Mac):
 // Mac:    "Click to continue"
 ```
 
-### Grammar Agreement (iOS 17+)
+### Grammar Agreement (iOS 15+)
 
 Use `^[...]` inflection syntax for automatic grammatical agreement:
 
@@ -203,6 +237,10 @@ Text("^[\(count) \("photo")](inflect: true) added")
 
 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
@@ -265,7 +303,7 @@ items.formatted(.list(type: .and))    // "Apples, Oranges, and Bananas" (EN)
                                       // "Apples, Oranges et Bananas" (FR)
 ```
 
-For the complete FormatStyle reference, custom styles, and RTL layout, see `references/formatstyle-locale.md`.
+For the complete FormatStyle reference, custom styles, and RTL layout, see [references/formatstyle-locale.md](references/formatstyle-locale.md).
 
 ## Right-to-Left (RTL) Layout
 
@@ -307,9 +345,9 @@ Text("+1 (555) 123-4567")
 
 ## Common Mistakes
 
-### DON'T: Use NSLocalizedString in new code
+### DON'T: Use NSLocalizedString in new Swift code
 ```swift
-// WRONG -- legacy API, verbose, no compiler integration with String Catalogs
+// LEGACY -- Xcode can export literal keys, but new Swift code should use modern APIs
 let title = NSLocalizedString("welcome_title", comment: "Welcome screen title")
 ```
 
@@ -387,6 +425,20 @@ 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.
 
@@ -409,10 +461,11 @@ Use Xcode scheme settings to override the app language without changing device l
 - [ ] `@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
 
 ## References
 
-- FormatStyle patterns: `references/formatstyle-locale.md`
-- String Catalogs guide: `references/string-catalogs.md`
-
+- FormatStyle patterns: [references/formatstyle-locale.md](references/formatstyle-locale.md)
+- String Catalogs guide: [references/string-catalogs.md](references/string-catalogs.md)

package/pipeline/skills/shared/external/ios-localization/evals/evals.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "ios-localization",
+  "evals": [
+    {
+      "id": 0,
+      "name": "generated-symbols-plurals",
+      "prompt": "I am updating an iOS 26 SwiftUI booking app for localization. We have a new Localizable.xcstrings file, a manually managed key named room_available whose English value is \"Book this room\", and a parameterized key named landmarks_count for \"42 landmarks\". Give me a concise migration plan and Swift snippets that use Xcode generated localizable symbols, plural-friendly placeholders, and modern string APIs. Also say what to do with old NSLocalizedString calls.",
+      "expected_output": "A concise migration plan that uses String Catalogs, generated symbols, correct positional named placeholders, modern String(localized:) / LocalizedStringResource guidance, plural variants, and legacy NSLocalizedString migration notes.",
+      "files": [],
+      "expectations": [
+        "Frames String Catalogs as the Xcode 15+ recommended workflow and does not claim they require iOS 17.",
+        "Mentions enabling Generate String Catalog Symbols and using stable manually managed keys.",
+        "Uses generated symbol examples such as Text(.roomAvailable) and Text(.landmarksCount(count: 42)).",
+        "Uses a positional named placeholder such as %1$(count)lld for the parameterized generated symbol.",
+        "Distinguishes String(localized:) for resolved strings from LocalizedStringResource for deferred or system-framework resolution.",
+        "Treats NSLocalizedString as legacy for new Swift code while acknowledging literal keys can still be exported or migrated."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "package-bundle-localization",
+      "prompt": "Please review this Swift package localization setup. SharedUI has Resources/Localizable.xcstrings and Package.swift includes .process(\"Resources\"). Inside the package target we wrote Text(\"Save\") and String(localized: \"settings.title\") with no bundle argument. In the app target the same keys work, but in the package they fall back to English. What should we change?",
+      "expected_output": "A review that explains package resources need explicit bundle lookup, recommends bundle: .module for Swift Package strings and SwiftUI Text, and keeps the guidance scoped to localization rather than package architecture.",
+      "files": [],
+      "expectations": [
+        "States that code outside the main app bundle needs an explicit bundle for localized resources.",
+        "Recommends String(localized: \"settings.title\", bundle: .module) or equivalent for Swift Package code.",
+        "Recommends SwiftUI Text with an explicit package bundle, such as Text(\"Save\", bundle: .module), or an equivalent localized label wrapper.",
+        "Does not claim SwiftUI Text inside a package automatically uses .module.",
+        "Mentions verifying the .xcstrings file is included in the package target resources.",
+        "Keeps the answer focused on localization bundle lookup rather than unrelated package architecture."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "formatstyle-boundary",
+      "prompt": "I am not adding new languages yet. I need to design a custom ParseableFormatStyle for follower counts like 12.5K, audit Date.IntervalFormatStyle usage, and format URLs for display. Should the iOS localization skill own this, or is there a better skill/domain? Give a short routing answer with the minimum localization advice that still matters.",
+      "expected_output": "A boundary answer that routes deep standalone FormatStyle API design to swift-formatstyle while giving minimal locale-facing localization cautions.",
+      "files": [],
+      "expectations": [
+        "Routes custom ParseableFormatStyle, Date.IntervalFormatStyle, and URL.FormatStyle design to the swift-formatstyle skill or domain.",
+        "Explains that ios-localization covers FormatStyle when the task is locale-aware display for localization and internationalization.",
+        "Keeps minimum localization advice, such as not hardcoding user-facing formats and respecting user locale.",
+        "Does not expand into a full custom FormatStyle implementation.",
+        "Does not collapse swift-formatstyle's standalone formatting scope into ios-localization."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/ios-localization/references/formatstyle-locale.md

@@ -1,6 +1,6 @@
 # FormatStyle & Locale-Aware Formatting
 
-Comprehensive reference for locale-aware formatting in iOS 15+ using `FormatStyle`. Never hard-code date, number, or measurement formats -- these break in every locale except the one you tested.
+Comprehensive reference for locale-aware formatting in iOS 15+ using `FormatStyle`. Never hard-code date, number, or measurement formats -- these break in every locale except the one you tested. `ios-localization` owns `FormatStyle` guidance when the issue is locale-aware user-facing display: numbers, dates, currency, units, names, lists, calendars, separators, and locale preview/testing. Locale-aware formatting matters even in single-language apps; explicitly recommend testing or previewing user-facing output under multiple locales. Use the `swift-formatstyle` skill for broader standalone FormatStyle API design.
 
 ## Contents
 
@@ -14,10 +14,27 @@ Comprehensive reference for locale-aware formatting in iOS 15+ using `FormatStyl
 - [Custom FormatStyle Implementation](#custom-formatstyle-implementation)
 - [Forcing a Specific Locale](#forcing-a-specific-locale)
 - [RTL Layout Deep Dive](#rtl-layout-deep-dive)
-- [@ScaledMetric for Dynamic Type](#scaledmetric-for-dynamic-type)
+- [`@ScaledMetric for Dynamic Type`](#scaledmetric-for-dynamic-type)
 - [Layout Testing with Accessibility Inspector](#layout-testing-with-accessibility-inspector)
 - [Quick Reference Table](#quick-reference-table)
 
+## Migration from Legacy Formatters
+
+`FormatStyle` (iOS 15+) replaces the older `Formatter` subclasses. If you encounter legacy code, migrate to `FormatStyle`:
+
+| Legacy | Modern replacement |
+|--------|-------------------|
+| `DateFormatter` | `.formatted(.dateTime...)` or `Date.FormatStyle` |
+| `NumberFormatter` | `.formatted(.number...)` or `IntegerFormatStyle` / `FloatingPointFormatStyle` |
+| `DateComponentsFormatter` | `Duration.formatted(.units(...))` or `.time(pattern:)` |
+| `MeasurementFormatter` | `Measurement.formatted(.measurement(...))` |
+| `DateIntervalFormatter` | `(start..<end).formatted(date:time:)` |
+| `PersonNameComponentsFormatter` | `.formatted(.name(style:))` |
+| `ByteCountFormatter` | `.formatted(.byteCount(style:))` |
+| `ListFormatter` | `.formatted(.list(type:))` |
+
+`FormatStyle` is value-type, `Sendable`, composable, and works directly in SwiftUI `Text` views. The legacy formatters are reference types that require manual locale and calendar configuration.
+
 ## Date Formatting
 
 ### Preset date and time styles
@@ -534,7 +551,7 @@ Text(phoneNumber)
 | Corner radius | Only rounding top-left/top-right | Round leading/trailing corners |
 | Swipe gestures | "Swipe right to delete" | "Swipe to leading edge" -- or use system gestures |
 
-## @ScaledMetric for Dynamic Type
+## `@ScaledMetric` for Dynamic Type
 
 Use `@ScaledMetric` to make custom spacing, icon sizes, and padding scale with the user's Dynamic Type setting.
 

package/pipeline/skills/shared/external/ios-localization/references/string-catalogs.md

@@ -13,15 +13,16 @@
 - [Device Variations](#device-variations)
 - [Exporting for Translators (XLIFF / xcloc)](#exporting-for-translators-xliff-xcloc)
 - [String Catalog JSON Structure](#string-catalog-json-structure)
+- [Generated Localizable Symbols (Xcode 26+)](#generated-localizable-symbols-xcode-26)
 - [Testing Strategies](#testing-strategies)
 - [Migration from .strings / .stringsdict](#migration-from-strings-stringsdict)
 - [Best Practices](#best-practices)
 
 ## What is a String Catalog?
 
-A String Catalog is a single `.xcstrings` file (JSON-based) that holds every localizable string in a target, along with all translations, plural forms, and device variations. It replaces the combination of `.strings` and `.stringsdict` files that previously required manual synchronization.
+A String Catalog is a single Xcode-managed `.xcstrings` file (JSON-based) that holds localizable strings in a target, along with translations, plural forms, and device variations. In Xcode 15 and later, String Catalogs are the recommended workflow for new localization work because they replace much of the manual synchronization previously required across `.strings` and `.stringsdict` files.
 
-**Availability:** Xcode 15+, all Apple platforms.
+**Availability:** Xcode 15+, all Apple platforms. String Catalogs are the recommended Xcode 15+ workflow for app localization. Xcode 26 adds generated localizable symbols on top of String Catalogs; do not describe catalogs themselves as requiring Xcode 26 or iOS 17.
 
 ## Creating a String Catalog
 
@@ -46,7 +47,7 @@ Text("Hello, world")                        // extracted
 Label("Settings", systemImage: "gear")      // extracted
 Button("Save") { }                          // extracted
 Toggle("Enable notifications", isOn: $on)   // extracted
-NavigationTitle("Home")                      // extracted
+.navigationTitle("Home")                     // extracted
 Section("Account") { }                      // extracted
 
 // NOT extracted -- computed or variable strings
@@ -72,10 +73,10 @@ static var title: LocalizedStringResource = "Title"  // extracted
 ```swift
 let x: String = "Not localized"          // plain String assignment
 print("debug info")                      // not user-facing
-NSLocalizedString("legacy", comment: "") // NOT auto-extracted into .xcstrings
+NSLocalizedString("legacy", comment: "") // legacy API; Xcode can export literal keys
 ```
 
-If automatic extraction misses a string, add it manually in the String Catalog editor.
+Prefer `String(localized:)`, SwiftUI localizable literals, or `LocalizedStringResource` in new Swift code so String Catalog syncing and generated-symbol workflows stay straightforward. If automatic extraction misses a string, add it manually in the String Catalog editor.
 
 ## Manual Key Management
 
@@ -90,7 +91,7 @@ Open the `.xcstrings` file in Xcode to use the visual editor:
 
 ### Key naming conventions
 
-Use structured key names for large projects:
+For manually-managed strings, use stable symbol-style keys rather than English text as the key. This prevents silent localization breaks when UI copy changes (a typo or rewording just creates a new key and stales the old one  -  no compiler error). With Xcode 26's generated symbols, stable keys also produce readable, predictable Swift accessors.
 
 ```text
 onboarding.welcome.title        -> "Welcome"
@@ -100,7 +101,15 @@ error.network.title             -> "Connection Error"
 error.network.message           -> "Check your internet and try again"
 ```
 
-For SwiftUI, the literal text IS the key by default. Use `String(localized:defaultValue:)` when you want a structured key that differs from the English text.
+Use `String(localized:defaultValue:)` when you want a structured key that differs from the English text:
+
+```swift
+let title = String(localized: "error.network.title",
+                   defaultValue: "Connection Error",
+                   comment: "Title for network error alert")
+```
+
+For SwiftUI auto-extracted strings, the literal text IS the key by default. This is fine for simple views. For any string you manage manually  -  shared keys, keys referenced across modules, or keys where copy changes frequently  -  use a stable key instead.
 
 ## Handling Strings in Non-SwiftUI Code
 
@@ -155,9 +164,8 @@ String(localized: "Hello")
 // .module refers to the package's resource bundle
 String(localized: "Hello", bundle: .module)
 
-// In SwiftUI, Text uses the module's bundle automatically
-// if the .xcstrings file is in the package's resources
-Text("Hello")  // looks up in the package's Localizable.xcstrings
+// In SwiftUI, pass the package bundle explicitly for package resources
+Text("Hello", bundle: .module)
 ```
 
 ### Framework
@@ -174,11 +182,17 @@ Each Swift package target that contains user-facing strings needs its own String
 
 ### Package.swift setup
 ```swift
-.target(
+let package = Package(
     name: "SharedUI",
-    dependencies: [],
-    resources: [
-        .process("Resources")  // Localizable.xcstrings goes here
+    defaultLocalization: "en",
+    targets: [
+        .target(
+            name: "SharedUI",
+            dependencies: [],
+            resources: [
+                .process("Resources")  // Localizable.xcstrings goes here
+            ]
+        )
     ]
 )
 ```
@@ -195,7 +209,7 @@ Sources/
 
 ### Accessing strings from the package
 ```swift
-// Inside the package -- .module resolves automatically
+// Inside the package -- bundle: .module resolves package-owned resources
 public struct SaveButton: View {
     public var body: some View {
         Button(String(localized: "Save", bundle: .module)) { }
@@ -203,7 +217,13 @@ public struct SaveButton: View {
 }
 ```
 
-**Important:** SwiftUI `Text("Save")` inside an SPM target looks up in `.module` automatically only if the `.xcstrings` file is properly included in the target's resources. Verify by checking that Xcode shows the file under the target in the project navigator.
+**Important:** Code outside the main app bundle needs an explicit bundle. Use `bundle: .module` in Swift packages, `Bundle(for:)` in frameworks, or the current-target bundle macro when available.
+
+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)`.
 
 ## Pluralization in String Catalogs
 
@@ -220,8 +240,8 @@ public struct SaveButton: View {
 
 ### English plural forms
 ```text
-one:   "%lld item in your cart"
-other: "%lld items in your cart"
+one:   "%1$(itemCount)lld item in your cart"
+other: "%1$(itemCount)lld items in your cart"
 ```
 
 ### Arabic plural forms (all six categories)
@@ -291,7 +311,7 @@ xcodebuild -importLocalizations \
 
 ## String Catalog JSON Structure
 
-The `.xcstrings` file is JSON. Understanding the structure enables programmatic manipulation (CI validation, batch updates, translation memory integration).
+The `.xcstrings` file is Xcode-managed JSON. Understanding the observed structure can help with parser-backed validation or careful batch updates, but prefer Xcode's editor/export/import workflows for normal localization changes and validate any automated edit before committing.
 
 ```json
 {
@@ -315,7 +335,19 @@ The `.xcstrings` file is JSON. Understanding the structure enables programmatic
         }
       }
     },
-    "%lld items": {
+    "room_available": {
+      "comment": "Button label on room search results",
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Book this room"
+          }
+        }
+      }
+    },
+    "%1$(count)lld items": {
       "localizations": {
         "en": {
           "variations": {
@@ -323,13 +355,13 @@ The `.xcstrings` file is JSON. Understanding the structure enables programmatic
               "one": {
                 "stringUnit": {
                   "state": "translated",
-                  "value": "%lld item"
+                  "value": "%1$(count)lld item"
                 }
               },
               "other": {
                 "stringUnit": {
                   "state": "translated",
-                  "value": "%lld items"
+                  "value": "%1$(count)lld items"
                 }
               }
             }
@@ -341,12 +373,88 @@ The `.xcstrings` file is JSON. Understanding the structure enables programmatic
 }
 ```
 
+Note the `"room_available"` key above: it uses `"extractionState": "manual"` and a stable symbol-style key with the English text in `"value"`, not in the key itself. 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.
+
 ### Translation states
 - `"new"` -- Xcode extracted the key but no translation exists
 - `"translated"` -- Translation provided
 - `"needs_review"` -- Marked for review (source string changed or manual flag)
 - `"stale"` -- Key no longer found in code (removed on next clean build)
 
+### Extraction states
+
+The `extractionState` field (separate from translation `state`) tracks how a key entered the catalog:
+
+| Value | Meaning |
+|-------|---------|
+| `extracted_with_value` | Xcode found the string in source code and extracted it automatically |
+| `manual` | Added by hand via the (+) button  -  not discovered from code. Xcode will never update or remove manual keys during build sync |
+| `stale` | Previously extracted from code, but Xcode can no longer find it. Orphaned translations still exist |
+| `migrated` | Converted from a legacy `.strings` or `.stringsdict` file |
+
+The `manual` state is significant: manual keys have the **Generate Swift Symbol** checkbox enabled by default, so they automatically produce compiler-checked `LocalizedStringResource` accessors when the build setting is on. Auto-extracted keys can also generate symbols  -  enable the checkbox per-key or use Refactor > Convert Strings to Symbols.
+
+## Generated Localizable Symbols (Xcode 26+)
+
+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.
+
+### Enabling symbol generation
+
+1. Build Settings > Localization > **Generate String Catalog Symbols** → `Yes` (on by default in new Xcode 26 projects)
+2. The catalog must use format version `"1.1"`  -  Xcode 26 writes this automatically when symbol generation metadata is present
+3. Each key has a **Generate Swift Symbol** checkbox in the String Catalog editor. Manual keys (added via the (+) button) have this enabled by default. Auto-extracted keys can opt in via Refactor > Convert Strings to Symbols, which enables the checkbox
+
+### How Xcode derives symbol names
+
+Xcode camelCases the key name, lowercasing the first segment:
+
+| Catalog key | Generated symbol |
+|-------------|-----------------|
+| `room_available` | `.roomAvailable` |
+| `settings.notifications.toggle` | `.settingsNotificationsToggle` |
+| `TITLE` | `.title` |
+
+Keys with format specifiers become functions. Use positional named placeholders such as `%1$(name)lld` for descriptive argument labels; bare `%lld` produces generic labels:
+
+| Catalog key | Format | Generated symbol |
+|-------------|--------|-----------------|
+| `landmarks_count` | `%1$(count)lld` | `.landmarksCount(count: Int)` |
+| `greeting` | `%@` | `.greeting(_ param1: String)` |
+
+You can rename parameters during refactoring for more descriptive signatures.
+
+### Using generated symbols
+
+```swift
+// Simple key  -  static property
+Text(.roomAvailable)
+
+// Parameterized key  -  function
+Text(.landmarksCount(count: 42))
+
+// Non-default table (Booking.xcstrings)
+Text(.Booking.confirmBookingCta)
+
+// In non-SwiftUI code
+let title = String(localized: .roomAvailable)
+let attributed = AttributedString(localized: .greeting(userName))
+```
+
+Code completion supports generated symbols  -  type `.` and choose from the menu.
+
+### Refactoring existing strings to symbols
+
+Select one or more keys in the String Catalog editor, Control-click, and choose **Refactor > Convert Strings to Symbols**. Xcode replaces string literal usage in code with the generated symbol. This is reversible via **Convert Symbols to Strings**.
+
+### Cross-module limitations
+
+Generated symbols are declared `internal`. Code in other modules cannot access them directly. Default to a public wrapper; reach for `xcstrings-tool` if the wrapper becomes unwieldy across many modules:
+
+- **Public wrapper** (default): Create a public extension on `LocalizedStringResource` that delegates to the internal symbols
+- **[xcstrings-tool](https://github.com/liamnichols/xcstrings-tool)**: A Swift Package Plugin that generates public constants from `.xcstrings` files  -  use this for heavier multi-module setups where maintaining manual wrappers becomes tedious
+
+For Swift Packages, the generated symbols use the `.module` bundle automatically. The `internal` visibility means only code within the same package target can reference them.
+
 ## Testing Strategies
 
 ### Scheme language override
@@ -460,3 +568,4 @@ String Catalogs and `.strings` files can coexist in the same target during migra
 5. **Automate coverage checks** -- integrate translation-coverage validation in CI to catch missing translations before release.
 6. **Export regularly** -- send updated `.xcloc` bundles to translators after each sprint or feature merge.
 7. **Test with pseudolocalizations in CI** -- run UI tests with double-length and RTL pseudo-languages to catch layout issues early.
+8. **Prefer stable keys with generated symbols** -- for manually-managed strings, use symbol-style keys and enable Generate String Catalog Symbols to get compile-time safety and autocompletion.