Surface issue in apps intents strings localization tooling

Modules/Sources/JetpackStatsWidgetsCore/AppIntents/SelectSiteIntent.swift

@@ -8,28 +8,38 @@ import AppIntents
 /// users' widgets to the default site.
 ///
 /// The localization keys are the app-bundle names of the identifiers Xcode generated for the
-/// legacy `.intentdefinition` ("gpCwrM", "ILcGmf"): GlotPress uploads them under the
-/// `ios-widget.` prefix, and the downloaded translations land in the app's
-/// `Localizable.strings` under those prefixed keys.
+/// legacy `.intentdefinition` ("gpCwrM", "ILcGmf"): The code freeze extracts these call sites
+/// into the GlotPress upload (`generate_app_intents_strings_for_glotpress`), and the downloaded
+/// translations land in the app's `Localizable.strings` under the prefixed keys.
 ///
-/// The keys must resolve in two bundles, because the OS picks a different one depending on
-/// version (verified on simulators): iOS 26 resolves the widget configuration UI's strings
-/// against the app bundle (whose GlotPress-managed `Localizable.strings` carries the prefixed
-/// keys in every locale), while iOS 17 resolves against the widget extension bundle, which
-/// ships static copies of the same prefixed keys in
-/// `Sources/JetpackStatsWidgets/Resources/<locale>.lproj/Localizable.strings`.
-/// A nested SPM package resource bundle is never consulted, so the strings cannot live in
-/// this package.
+/// iOS 18 and later resolve the widget configuration UI's strings against the app bundle,
+/// whose GlotPress-managed `Localizable.strings` carries the prefixed keys in every locale
+/// (verified on simulators; a nested SPM package resource bundle is never consulted).
+/// iOS 17 resolves against the widget extension bundle only, with no fallback to the app
+/// bundle, so it shows the English default values; we accept English there rather than
+/// shipping per-locale copies in the extension.
 public struct SelectSiteIntent: WidgetConfigurationIntent, CustomIntentMigratedAppIntent {
     public static let intentClassName = "SelectSiteIntent"
 
-    public static let title = LocalizedStringResource("ios-widget.gpCwrM", defaultValue: "Select Site")
+    public static let title = LocalizedStringResource(
+        "ios-widget.gpCwrM",
+        defaultValue: "Select Site",
+        comment:
+            "This text is used when the user is configuring the iOS widget to suggest them to select the site to configure the widget for"
+    )
 
     // The legacy intent was ineligible for Siri suggestions; keep this
     // configuration-only intent out of Shortcuts and Spotlight the same way.
     public static let isDiscoverable = false
 
-    @Parameter(title: LocalizedStringResource("ios-widget.ILcGmf", defaultValue: "Site"))
+    @Parameter(
+        title: LocalizedStringResource(
+            "ios-widget.ILcGmf",
+            defaultValue: "Site",
+            comment:
+                "This text is used when the user is configuring the iOS widget, as a label for the dropdown to select the site to configure it for"
+        )
+    )
     public var site: SiteEntity?
 
     public init() {}

Modules/Sources/JetpackStatsWidgetsCore/AppIntents/SiteEntity.swift

@@ -7,11 +7,16 @@ import Foundation
 /// the `identifier` of the legacy SiriKit `Site` object so that widget configurations created
 /// before the App Intents migration keep resolving to the same site.
 ///
-/// The "ios-widget.ILcGmf" localization key resolves against the app bundle on iOS 26 and
-/// the widget extension bundle on iOS 17; see `SelectSiteIntent` for the details.
+/// The "ios-widget.ILcGmf" localization key resolves against the app bundle on iOS 18 and
+/// later; see `SelectSiteIntent` for the details.
 public struct SiteEntity: AppEntity {
     public static let typeDisplayRepresentation = TypeDisplayRepresentation(
-        name: LocalizedStringResource("ios-widget.ILcGmf", defaultValue: "Site")
+        name: LocalizedStringResource(
+            "ios-widget.ILcGmf",
+            defaultValue: "Site",
+            comment:
+                "This text is used when the user is configuring the iOS widget, as a label for the dropdown to select the site to configure it for"
+        )
     )
 
     public static var defaultQuery: SiteEntityQuery { SiteEntityQuery() }