@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,369 +1,254 @@
-# String Catalogs (.xcstrings) -- Detailed Reference
+# String Catalogs in Depth
 
 ## Contents
 
-- [What is a String Catalog?](#what-is-a-string-catalog)
-- [Creating a String Catalog](#creating-a-string-catalog)
-- [Automatic String Extraction](#automatic-string-extraction)
-- [Manual Key Management](#manual-key-management)
-- [Handling Strings in Non-SwiftUI Code](#handling-strings-in-non-swiftui-code)
-- [Bundle Access Patterns](#bundle-access-patterns)
-- [Multi-Module / SPM Localization](#multi-module-spm-localization)
-- [Pluralization in String Catalogs](#pluralization-in-string-catalogs)
-- [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 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. 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
-
-1. File > New > File > String Catalog
-2. Name it `Localizable.xcstrings` (the default table name, matching the legacy `Localizable.strings`)
-3. Place it in the target's source directory
-4. Add target languages in Project > Info > Localizations
-
-For a non-default table name (e.g., `Onboarding.xcstrings`), reference it explicitly:
+1. [What a catalog is](#what-a-catalog-is)
+2. [Creating one](#creating-one)
+3. [What extraction picks up](#what-extraction-picks-up)
+4. [Managing keys by hand](#managing-keys-by-hand)
+5. [Strings outside SwiftUI](#strings-outside-swiftui)
+6. [Bundles](#bundles)
+7. [Swift packages and multiple modules](#swift-packages-and-multiple-modules)
+8. [Plurals](#plurals)
+9. [Device variants](#device-variants)
+10. [Working with translators](#working-with-translators)
+11. [The JSON format](#the-json-format)
+12. [Generated symbols (Xcode 26)](#generated-symbols-xcode-26)
+13. [Testing](#testing)
+14. [Migrating from .strings and .stringsdict](#migrating-from-strings-and-stringsdict)
+15. [Practices that scale](#practices-that-scale)
+
+## What a catalog is
+
+One `.xcstrings` file per target, stored as JSON, holds the source strings,
+their translations, plural forms and device variants. Catalogs arrived in
+Xcode 15 and work on every platform Xcode targets. Xcode 26 adds generated Swift
+symbols as an extra layer; the catalog itself does not need Xcode 26.
+
+## Creating one
+
+1. File > New > File, choose String Catalog.
+2. Call it `Localizable.xcstrings`. That name is the default table, the same
+   role `Localizable.strings` used to play.
+3. Put it in the target's source folder.
+4. Add languages under Project > Info > Localizations.
+
+Any other name is a separate table. A file named `Help.xcstrings` is read with
+`String(localized: "faq.title", table: "Help")`.
+
+## What extraction picks up
+
+The compiler finds localizable strings on every build by looking at known
+initializers and parameter types.
 
 ```swift
-String(localized: "welcome.title", table: "Onboarding")
-```
-
-## Automatic String Extraction
-
-On every build, Xcode scans source files and extracts strings from known localizable initializers. Extraction is compiler-driven -- it recognizes these patterns:
-
-### SwiftUI (LocalizedStringKey)
-```swift
-Text("Hello, world")                        // extracted
-Label("Settings", systemImage: "gear")      // extracted
-Button("Save") { }                          // extracted
-Toggle("Enable notifications", isOn: $on)   // extracted
-.navigationTitle("Home")                     // extracted
-Section("Account") { }                      // extracted
-
-// NOT extracted -- computed or variable strings
-Text(viewModel.title)                       // not extracted (runtime value)
-Text(verbatim: "v1.2.3")                    // not extracted (verbatim skips localization)
-```
-
-### Foundation (String(localized:))
-```swift
-String(localized: "No results found")               // extracted
-String(localized: "error.title",
-       defaultValue: "Something went wrong",
-       comment: "Generic error alert title")         // extracted with default + comment
-```
-
-### LocalizedStringResource
-```swift
-LocalizedStringResource("Order placed")              // extracted
-static var title: LocalizedStringResource = "Title"  // extracted
-```
+// Picked up
+Text("Welcome aboard")
+Label("Downloads", systemImage: "arrow.down.circle")
+Button("Retry") { }
+Toggle("Offline mode", isOn: $offline)
+Section("Account") { }
+someView.navigationTitle("Library")
+
+String(localized: "sync.failed", defaultValue: "Sync failed", comment: "Toast after a failed sync")
+LocalizedStringResource("Open in Maps")
+
+enum Copy {
+    static let emptyInbox: LocalizedStringResource = "Nothing new today"
+}
 
-### What is NOT extracted
-```swift
-let x: String = "Not localized"          // plain String assignment
-print("debug info")                      // not user-facing
-NSLocalizedString("legacy", comment: "") // legacy API; Xcode can export literal keys
+// Not picked up
+Text(viewModel.headline)           // value known only at runtime
+Text(verbatim: "v2.4.1")           // opts out of localization
+let screenName = "Library"         // plain String
+print("Library opened")            // logging
 ```
 
-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
+`NSLocalizedString` is legacy, but Xcode can still export its literal keys.
+If extraction misses something, add the key in the catalog editor.
 
-Open the `.xcstrings` file in Xcode to use the visual editor:
+## Managing keys by hand
 
-- **Add key**: Click + at the bottom of the key list
-- **Remove key**: Select key, press Delete (marks as Stale, removed on next build if no code reference)
-- **Edit comment**: Select key, edit the Comment field (provides translator context)
-- **Mark state**: Right-click a translation to set Needs Review / Reviewed
-- **Vary by plural**: Select a key, click Vary > Plural to add plural categories
-- **Vary by device**: Select a key, click Vary > Device to add iPhone/iPad/Mac variants
+In the editor:
 
-### Key naming conventions
+- (+) adds a key.
+- Delete marks a key Stale; if no code references it, the next build drops it.
+- The Comment field gives translators context they cannot see in the UI.
+- Right-click to mark an entry Needs Review or Reviewed.
+- Vary > Plural and Vary > Device add variants.
 
-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.
+Name keys like stable identifiers, grouped with dots:
 
-```text
-onboarding.welcome.title        -> "Welcome"
-onboarding.welcome.subtitle     -> "Get started in minutes"
-settings.notifications.toggle   -> "Enable Notifications"
-error.network.title             -> "Connection Error"
-error.network.message           -> "Check your internet and try again"
 ```
-
-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")
+checkout.summary.title
+checkout.summary.total
+error.offline.title
+error.offline.message
 ```
 
-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.
+With Xcode 26 symbols these keys also become readable, predictable accessors.
+For simple SwiftUI screens it is fine to let the literal be the key. Strings
+that are shared, used across modules, or reworded often should get a stable key.
 
-## Handling Strings in Non-SwiftUI Code
-
-### View models, services, and utilities
+## Strings outside SwiftUI
 
 ```swift
-class OrderService {
-    func statusMessage(for order: Order) -> String {
-        switch order.status {
-        case .shipped:
-            return String(localized: "order.status.shipped",
-                          defaultValue: "Your order has shipped!",
-                          comment: "Order status when item is in transit")
+struct DeliveryStatusText {
+    func text(for status: DeliveryStatus, eta: Date) -> String {
+        switch status {
+        case .preparing:
+            String(localized: "delivery.preparing",
+                   defaultValue: "The kitchen is preparing your order",
+                   comment: "Order tracking, first step")
+        case .onTheWay:
+            String(localized: "delivery.on_the_way",
+                   defaultValue: "Arriving \(eta, format: .dateTime.month().day())",
+                   comment: "Order tracking with the expected day")
         case .delivered:
-            return String(localized: "order.status.delivered",
-                          defaultValue: "Delivered on \(order.deliveryDate!, format: .dateTime.month().day())",
-                          comment: "Order status with delivery date")
-        case .processing:
-            return String(localized: "order.status.processing",
-                          defaultValue: "Processing your order...",
-                          comment: "Order status while being prepared")
+            String(localized: "delivery.done",
+                   defaultValue: "Delivered",
+                   comment: "Order tracking, final step")
         }
     }
 }
-```
-
-### Specifying table and bundle
 
-```swift
-// From a specific table
-String(localized: "greeting",
-       table: "Onboarding",
-       comment: "First-launch greeting")
-
-// From a specific bundle (framework or Swift package)
-String(localized: "button.save",
-       table: "SharedUI",
-       bundle: .module,
-       comment: "Save button in shared component")
+let help = String(localized: "faq.title", table: "Help")
+let packaged = String(localized: "player.skip",
+                      table: "Player",
+                      bundle: .module,
+                      comment: "Skips 15 seconds forward")
 ```
 
-## Bundle Access Patterns
+## Bundles
 
-### Main app
-```swift
-// Uses Bundle.main by default -- no bundle argument needed
-String(localized: "Hello")
-```
+- App target: `Bundle.main` is implied, so pass nothing.
+- Swift package: `.module` is the package's resource bundle. Use
+  `String(localized: "...", bundle: .module)`, and in SwiftUI pass it
+  explicitly, `Text("...", bundle: .module)`. `Text` does not pick up the
+  package bundle on its own.
+- Framework: find the bundle through a class that lives in it.
 
-### Swift Package (SPM)
 ```swift
-// .module refers to the package's resource bundle
-String(localized: "Hello", bundle: .module)
+final class ChartsBundleToken {}
 
-// In SwiftUI, pass the package bundle explicitly for package resources
-Text("Hello", bundle: .module)
+let chartsBundle = Bundle(for: ChartsBundleToken.self)
+let axisLabel = String(localized: "axis.time", bundle: chartsBundle)
 ```
 
-### Framework
-```swift
-// Reference the framework's bundle
-let frameworkBundle = Bundle(for: MyFrameworkClass.self)
-String(localized: "Hello",
-       bundle: .init(frameworkBundle.bundleURL))
-```
+Any code that is not in the main bundle has to name its bundle: `.module` in a
+package, `Bundle(for:)` in a framework, or the current-target bundle macro
+where the toolchain provides it.
 
-## Multi-Module / SPM Localization
+## Swift packages and multiple modules
 
-Each Swift package target that contains user-facing strings needs its own String Catalog.
+Every package target that shows text needs its own catalog.
 
-### Package.swift setup
 ```swift
+// swift-tools-version: 6.0
+import PackageDescription
+
 let package = Package(
-    name: "SharedUI",
+    name: "ProfileKit",
     defaultLocalization: "en",
     targets: [
-        .target(
-            name: "SharedUI",
-            dependencies: [],
-            resources: [
-                .process("Resources")  // Localizable.xcstrings goes here
-            ]
-        )
+        .target(name: "ProfileKit", resources: [.process("Resources")])
     ]
 )
+// Catalog path: Sources/ProfileKit/Resources/Localizable.xcstrings
 ```
 
-### Directory structure
-```text
-Sources/
-  SharedUI/
-    Resources/
-      Localizable.xcstrings    <- String Catalog for this module
-    Views/
-      ButtonStyles.swift
-```
-
-### Accessing strings from the package
 ```swift
-// Inside the package -- bundle: .module resolves package-owned resources
-public struct SaveButton: View {
+public struct SignOutButton: View {
+    let action: () -> Void
     public var body: some View {
-        Button(String(localized: "Save", bundle: .module)) { }
+        Button(String(localized: "Sign out", bundle: .module), action: action)
     }
 }
 ```
 
-**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
-
-### Setup
+When a package keeps falling back to the development language, check setup
+before lookup:
 
-1. Write code with integer interpolation:
-   ```swift
-   Text("\(itemCount) items in your cart")
-   ```
-2. Build the project -- Xcode adds the key to the String Catalog
-3. Open the String Catalog, select the key
-4. Click "Vary by Plural" in the inspector
-5. Fill in plural forms for each language
+1. `defaultLocalization` is set in `Package.swift`.
+2. The target's `resources` processes the catalog's folder, for example
+   `.process("Resources")`.
+3. The catalog file is actually inside that folder.
 
-### English plural forms
-```text
-one:   "%1$(itemCount)lld item in your cart"
-other: "%1$(itemCount)lld items in your cart"
-```
-
-### Arabic plural forms (all six categories)
-```text
-zero:  "لا توجد عناصر في سلتك"
-one:   "عنصر واحد في سلتك"
-two:   "عنصران في سلتك"
-few:   "%lld عناصر في سلتك"        (3-10)
-many:  "%lld عنصرًا في سلتك"       (11-99)
-other: "%lld عنصر في سلتك"         (100+)
-```
+## Plurals
 
-### Multiple plural variables
+1. Write the string with an integer interpolation.
+2. Build.
+3. Select the key in the catalog.
+4. Choose Vary by Plural in the inspector.
+5. Fill each form every language needs.
 
-When a string has two integer interpolations, the String Catalog shows a matrix of plural combinations:
+English, with a named positional placeholder:
 
-```swift
-Text("\(photoCount) photos in \(albumCount) albums")
-// English needs: one/one, one/other, other/one, other/other
-```
+| Category | Value |
+|---|---|
+| one | `%1$(songCount)lld song` |
+| other | `%1$(songCount)lld songs` |
 
-## Device Variations
+Arabic fills all six categories: zero, one, two, few (`%lld` ...), many
+(`%lld` ...) and other (`%lld` ...), each with its own wording.
 
-Enable "Vary by Device" for a key to provide different text on iPhone, iPad, Apple Watch, Mac, Apple TV, and Apple Vision Pro.
+Two integer interpolations in one string create a matrix. For
+`"\(photos) photos in \(albums) albums"` English needs one/one, one/other,
+other/one and other/other.
 
-```swift
-// Code is the same everywhere:
-Text("Tap to continue")
-
-// String Catalog provides:
-// iPhone: "Tap to continue"
-// iPad:   "Tap or click to continue"
-// Mac:    "Click to continue"
-// Vision: "Look and tap to continue"
-```
+## Device variants
 
-## Exporting for Translators (XLIFF / xcloc)
+Vary by Device lets a key read differently on iPhone, iPad, Apple Watch, Mac,
+Apple TV and Apple Vision Pro. The Swift call site does not change.
 
-### Export
+## Working with translators
 
-1. Product > Export Localizations... (or `xcodebuild -exportLocalizations`)
-2. Select target languages
-3. Xcode creates `.xcloc` bundles (one per language)
-4. Send `.xcloc` files to translators (they contain XLIFF 1.2 inside)
+Export with Product > Export Localizations... or on the command line. The
+result is one `.xcloc` bundle per language, with XLIFF 1.2 inside.
 
-### Command-line export
 ```bash
 xcodebuild -exportLocalizations \
-    -project MyApp.xcodeproj \
-    -localizationPath ./Localizations \
-    -exportLanguage de -exportLanguage ja -exportLanguage ar
+  -project Journal.xcodeproj \
+  -localizationPath ./l10n-out \
+  -exportLanguage fr \
+  -exportLanguage ko
 ```
 
-### Import
-
-1. Product > Import Localizations...
-2. Select the completed `.xcloc` file
-3. Xcode merges translations into the String Catalog
-4. Review changes in the diff viewer
+Bring translations back with Product > Import Localizations...; Xcode merges
+them into the catalog, and the diff viewer shows what changed.
 
-### Command-line import
 ```bash
 xcodebuild -importLocalizations \
-    -project MyApp.xcodeproj \
-    -localizationPath ./Localizations/de.xcloc
+  -project Journal.xcodeproj \
+  -localizationPath ./l10n-in/fr.xcloc
 ```
 
-## String Catalog JSON Structure
+## The JSON format
 
-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.
+Edit through the Xcode editor or the export/import round trip where possible.
+Knowing the format helps when a parser-based check or a careful bulk edit is
+needed; validate any scripted change before committing it.
 
 ```json
 {
-  "sourceLanguage": "en",
-  "version": "1.0",
-  "strings": {
-    "Welcome, %@!": {
-      "comment": "Greeting shown on home screen with user name",
-      "localizations": {
-        "en": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Welcome, %@!"
-          }
-        },
-        "de": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Willkommen, %@!"
-          }
-        }
-      }
-    },
-    "item_available": {
-      "comment": "Button label on product search results",
-      "extractionState": "manual",
-      "localizations": {
-        "en": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Add this item"
-          }
-        }
+  "sourceLanguage" : "en",
+  "version" : "1.1",
+  "strings" : {
+    "cart_empty" : {
+      "comment" : "Shown when the cart has no items",
+      "extractionState" : "manual",
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Your cart is empty" } },
+        "de" : { "stringUnit" : { "state" : "translated", "value" : "Dein Warenkorb ist leer" } }
       }
     },
-    "%1$(count)lld items": {
-      "localizations": {
-        "en": {
-          "variations": {
-            "plural": {
-              "one": {
-                "stringUnit": {
-                  "state": "translated",
-                  "value": "%1$(count)lld item"
-                }
-              },
-              "other": {
-                "stringUnit": {
-                  "state": "translated",
-                  "value": "%1$(count)lld items"
-                }
-              }
+    "reviews_count" : {
+      "localizations" : {
+        "en" : {
+          "variations" : {
+            "plural" : {
+              "one"   : { "stringUnit" : { "state" : "translated", "value" : "%lld review" } },
+              "other" : { "stringUnit" : { "state" : "translated", "value" : "%lld reviews" } }
             }
           }
         }
@@ -373,199 +258,187 @@ The `.xcstrings` file is Xcode-managed JSON. Understanding the observed structur
 }
 ```
 
-Note the `"item_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.
+The top level has `sourceLanguage`, `version` and `strings`. Each key may hold
+`comment`, `extractionState` and `localizations`, where every language has a
+`stringUnit` with `state` and `value`. Plurals nest under
+`localizations.<lang>.variations.plural.<category>.stringUnit`. Note that
+`cart_empty` is a manual key: the English copy lives in `value`, not in the key.
 
-### 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)
+Translation `state`:
 
-### Extraction states
+| State | Meaning |
+|---|---|
+| `new` | Not translated yet |
+| `translated` | Done |
+| `needs_review` | Source text changed or someone flagged it |
+| `stale` | The key is gone from code; a clean build removes it |
 
-The `extractionState` field (separate from translation `state`) tracks how a key entered the catalog:
+`extractionState`:
 
-| 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 |
+| State | Meaning |
+|---|---|
+| `extracted_with_value` | Found in source by the build |
+| `manual` | Added by hand; build sync never changes or deletes it |
+| `stale` | No longer found; its translations are orphaned |
+| `migrated` | Came from `.strings` or `.stringsdict` |
 
-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.
+Manual keys have Generate Swift Symbol on by default and, with the build
+setting on, turn into compiler-checked `LocalizedStringResource` accessors.
+Extracted keys opt in one at a time or through Convert Strings to Symbols.
 
-## Generated Localizable Symbols (Xcode 26+)
+## 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.
+Frame answers the same way as in the main skill: catalogs are the Xcode 15+
+workflow; generated symbols are Xcode 26's typed layer on top. Never state that
+catalogs need Xcode 26 or iOS 17.
 
-### Enabling symbol generation
+Xcode 26 writes format version `"1.1"` into the file as soon as symbol metadata
+exists.
 
-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
+Naming: the key is camelCased and its first segment lowercased.
 
-### How Xcode derives symbol names
+| Key | Symbol |
+|---|---|
+| `cart_empty` | `.cartEmpty` |
+| `profile.privacy.header` | `.profilePrivacyHeader` |
+| `DONE` | `.done` |
 
-Xcode camelCases the key name, lowercasing the first segment:
+Keys with format specifiers turn into functions. A named positional placeholder
+such as `%1$(nights)lld` gives a readable label; a bare `%lld` gives a generic
+one.
 
-| Catalog key | Generated symbol |
-|-------------|-----------------|
-| `item_available` | `.itemAvailable` |
-| `settings.notifications.toggle` | `.settingsNotificationsToggle` |
-| `TITLE` | `.title` |
+| Key and value | Symbol |
+|---|---|
+| `stay_length` = `%1$(nights)lld nights` | `.stayLength(nights: Int)` |
+| `welcome_user` = `Hi %@` | `.welcomeUser(_ arg1: String)` |
 
-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 |
-|-------------|--------|-----------------|
-| `products_count` | `%1$(count)lld` | `.productsCount(count: Int)` |
-| `greeting` | `%@` | `.greeting(_ param1: String)` |
-
-You can rename parameters during refactoring for more descriptive signatures.
-
-### Using generated symbols
+Parameters can be renamed while refactoring.
 
 ```swift
-// Simple key  -  static property
-Text(.itemAvailable)
-
-// Parameterized key  -  function
-Text(.productsCount(count: 42))
+Text(.cartEmpty)
+Text(.stayLength(nights: 4))
 
-// Non-default table (Checkout.xcstrings)
-Text(.Checkout.confirmOrderCta)
-
-// In non-SwiftUI code
-let title = String(localized: .itemAvailable)
-let attributed = AttributedString(localized: .greeting(userName))
+let plain = String(localized: .cartEmpty)
+let styled = AttributedString(localized: .welcomeUser(member.firstName))
 ```
 
-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**.
+Code completion lists the symbols after you type `.`.
 
-### Cross-module limitations
+Converting existing literals: select the keys, Control-click, Refactor > Convert
+Strings to Symbols. Xcode rewrites the literals at their call sites. Convert
+Symbols to Strings goes the other way.
 
-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:
+Across modules: symbols are `internal`. The usual fix is a public extension on
+`LocalizedStringResource` that forwards to them:
 
-- **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.
+```swift
+public extension LocalizedStringResource {
+    static var sharedRetry: LocalizedStringResource { .retryButton }
+}
+```
 
-## Testing Strategies
+When those wrappers become tedious, `xcstrings-tool`, an open-source Swift
+package plugin, generates public constants for you.
 
-### Scheme language override
+Inside a Swift package, generated symbols read from the `.module` bundle
+automatically, and they are only visible within the same package target.
 
-Edit Scheme > Run > Options > App Language. Choose any added language to launch the app in that locale without changing the device/simulator system language.
+## Testing
 
-### Pseudolocalization options
+Scheme override: Edit Scheme > Run > Options > App Language starts the app in
+another language without touching the system setting.
 
-Xcode provides built-in pseudolocalization modes (Edit Scheme > Run > Options > App Language):
+Pseudolanguages from the same menu:
 
-| Option | Effect | Catches |
-|--------|--------|---------|
-| Accented Pseudolanguage | Adds accents: "Hello" -> "[Hellо]" | Hardcoded strings (unlocalized text is obvious) |
-| Right-to-Left Pseudolanguage | Forces RTL layout | Layout mirroring bugs |
-| Double-Length Pseudolanguage | Doubles all strings | Truncation and overflow |
-| Bounded String Pseudolanguage | Wraps strings in brackets | Missing localizations |
+| Pseudolanguage | Finds |
+|---|---|
+| Accented | Hard-coded strings that bypass lookup |
+| Right-to-Left | Mirroring bugs |
+| Double-Length | Truncation and overflow |
+| Bounded String | Missing localizations (strings are wrapped in brackets) |
 
-### UI tests with locale override
+UI test in a specific locale:
 
 ```swift
-func testGermanLayout() {
-    let app = XCUIApplication()
-    app.launchArguments += ["-AppleLanguages", "(de)"]
-    app.launchArguments += ["-AppleLocale", "de_DE"]
-    app.launch()
-
-    // Verify no truncation on key screens
-    let saveButton = app.buttons["Speichern"]
-    XCTAssertTrue(saveButton.exists)
-    XCTAssertTrue(saveButton.isHittable)
-}
-```
-
-### Snapshot testing per locale
-
-Use a snapshot testing library to capture screenshots in multiple locales and compare them for layout regressions:
-
-```swift
-let locales = ["en_US", "de_DE", "ar_SA", "ja_JP"]
-for locale in locales {
-    app.launchArguments = ["-AppleLanguages", "(\(locale.prefix(2)))"]
-    app.launch()
-    // Capture and compare snapshot
+import XCTest
+
+final class GermanCheckoutUITests: XCTestCase {
+    @MainActor
+    func testPayButtonIsLocalized() {
+        let app = XCUIApplication()
+        app.launchArguments += ["-AppleLanguages", "(de)", "-AppleLocale", "de_DE"]
+        app.launch()
+
+        let pay = app.buttons["Jetzt bezahlen"]
+        XCTAssertTrue(pay.exists)
+        XCTAssertTrue(pay.isHittable)
+    }
 }
 ```
 
-### Translation coverage validation
+Screenshot comparison per locale: loop over `en_US`, `de_DE`, `ar_SA` and
+`ja_JP`, set `-AppleLanguages` for each, launch, capture, compare against the
+stored image.
 
-Check that all keys are translated before release:
+Translation coverage in CI: parse the catalog and fail when any language entry
+is untranslated or empty.
 
-```bash
-# Parse the .xcstrings JSON and check for "new" or empty states
-python3 -c "
+```python
+#!/usr/bin/env python3
 import json, sys
-with open('Localizable.xcstrings') as f:
-    data = json.load(f)
-missing = []
-for key, info in data['strings'].items():
-    for lang, loc in info.get('localizations', {}).items():
-        unit = loc.get('stringUnit', {})
-        if unit.get('state') in ('new', None) or not unit.get('value'):
-            missing.append(f'{lang}: {key}')
-if missing:
-    print('Missing translations:')
-    for m in missing: print(f'  {m}')
-    sys.exit(1)
-print('All translations complete.')
-"
-```
-
-## Migration from .strings / .stringsdict
 
-### Automatic migration
-
-1. Select the `.strings` file in the project navigator
-2. Right-click > Migrate to String Catalog...
-3. Xcode creates a `.xcstrings` file with all existing keys and translations
-4. Verify in the String Catalog editor
-5. Remove the old `.strings` / `.stringsdict` files from the target
+catalog = json.load(open(sys.argv[1], encoding="utf-8"))
+gaps = []
+for key, entry in catalog.get("strings", {}).items():
+    for lang, loc in entry.get("localizations", {}).items():
+        units = [loc["stringUnit"]] if "stringUnit" in loc else [
+            v["stringUnit"]
+            for group in loc.get("variations", {}).values()
+            for v in group.values() if "stringUnit" in v
+        ]
+        for unit in units:
+            if unit.get("state", "new") == "new" or not unit.get("value"):
+                gaps.append(f"{lang}: {key}")
+
+print("\n".join(gaps) or "all strings translated")
+sys.exit(1 if gaps else 0)
+```
 
-### Manual migration
+## Migrating from .strings and .stringsdict
 
-If automatic migration fails (complex bundle setups, CocoaPods):
+Automatic: right-click the `.strings` file, choose Migrate to String Catalog...,
+check the result, then remove the old files from the target.
 
-1. Create a new `Localizable.xcstrings`
-2. Build to extract keys from code
-3. Copy translations from old `.strings` files into the String Catalog editor
-4. Copy plural rules from `.stringsdict` into plural variants
-5. Remove old files
+By hand, when a bundle setup is unusual or files come from CocoaPods:
 
-### Migration checklist
+1. Create a new catalog.
+2. Build so extraction fills it.
+3. Copy translations across from the old files.
+4. Rebuild `.stringsdict` rules as plural variants.
+5. Remove the legacy files.
 
-- [ ] All `.strings` keys present in the new String Catalog
-- [ ] All `.stringsdict` plural rules converted to String Catalog plural variants
-- [ ] Bundle references updated (if custom bundle was used)
-- [ ] Build succeeds with no missing-localization warnings
-- [ ] Test every language the app supports
-- [ ] Remove old `.strings` and `.stringsdict` files from the target
-- [ ] Commit the `.xcstrings` file (it is JSON, diffs well in version control)
+Before calling it done:
 
-### Coexistence
+- [ ] Every key made it across
+- [ ] Plurals are variants now
+- [ ] Custom bundle references point to the right place
+- [ ] The build shows no missing-localization warnings
+- [ ] Every language was run
+- [ ] Legacy files are gone
+- [ ] `.xcstrings` is committed (it diffs cleanly as JSON)
 
-String Catalogs and `.strings` files can coexist in the same target during migration. Xcode resolves keys from the String Catalog first, then falls back to `.strings`. Remove legacy files after verifying the migration.
+During the transition both formats work: lookup tries the catalog first, then
+the `.strings` file. Delete the legacy file once you have verified the catalog.
 
-## Best Practices
+## Practices that scale
 
-1. **One String Catalog per target** -- keep `Localizable.xcstrings` as the single source of truth for each target.
-2. **Use comments** -- provide context for every ambiguous key. Translators cannot see your UI.
-3. **Review extraction on every build** -- new keys appear with state "new". Translate them promptly.
-4. **Version control the .xcstrings file** -- it is JSON and diffs clearly. Review translation changes in PRs.
-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.
+1. One catalog per target as the source of truth.
+2. A comment on every ambiguous key; translators never see the screen.
+3. After each build, look for keys in state `new` and get them translated.
+4. Keep `.xcstrings` in version control and review translation diffs in pull
+   requests.
+5. Run a translation coverage check in CI.
+6. Send `.xcloc` exports to translators at every sprint or feature merge.
+7. Run UI tests under the double-length and RTL pseudolanguages in CI.
+8. Prefer stable keys with generated symbols for compile-time checking and
+   autocompletion.