Localization: drop preview-string lint; document that the tooling excludes them

jkmassel · jkmassel · commit 6f45ab999dda · 2026-06-26T12:05:35.000-06:00
`xcstringstool sync` admits only unconditionally-compiled strings (`visibility:
nil`) into `Localizable.xcstrings`. Preview, `PreviewProvider`, and `#if DEBUG`
literals are tagged with a non-empty `visibility` by `extract` and dropped by
`sync` before they can reach the catalog or GlotPress.

The CI lint and the `Text(verbatim:)` preview swaps guarded a case the tooling
already handles, so revert both and document the actual extract/sync contract in
docs/localization.md instead.
diff --git a/.buildkite/commands/lint-swiftui-preview-strings.sh b/.buildkite/commands/lint-swiftui-preview-strings.sh
diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml
@@ -163,13 +163,6 @@ steps:
           - github_commit_status:
               context: "Verify String Catalog Coverage"
 
-      - label: ":sleuth_or_spy: Lint SwiftUI Preview Strings"
-        command: .buildkite/commands/lint-swiftui-preview-strings.sh
-        plugins: [$CI_TOOLKIT_PLUGIN]
-        notify:
-          - github_commit_status:
-              context: "Lint SwiftUI Preview Strings"
-
   #################
   # Claude Build Analysis - dynamically uploaded so Build result conditions evaluate at runtime after the wait
   #################
diff --git a/Modules/Sources/AsyncImageKit/Views/CachedAsyncImage.swift b/Modules/Sources/AsyncImageKit/Views/CachedAsyncImage.swift
@@ -177,13 +177,13 @@ fileprivate let videoURL = URL(
     CachedAsyncImage(url: testURL) { image in
         image.resizable().scaledToFit()
     } placeholder: {
-        Text(verbatim: "Loading")
+        Text("Loading")
     }
 }
 
 #Preview("Image that never loads") {
     CachedAsyncImage(url: nil) { _ in
-        Text(verbatim: "This shouldn't be visible")
+        Text("This shouldn't be visible")
     } placeholder: {
         ProgressView("Forever loading...")
     }
@@ -220,6 +220,6 @@ fileprivate let videoURL = URL(
     CachedAsyncImage(videoUrl: videoURL) { image in
         image.resizable().aspectRatio(contentMode: .fit)
     } placeholder: {
-        Text(verbatim: "Loading")
+        Text("Loading")
     }
 }
diff --git a/Modules/Sources/JetpackStats/Views/BadgeTrendIndicator.swift b/Modules/Sources/JetpackStats/Views/BadgeTrendIndicator.swift
@@ -26,15 +26,15 @@ struct BadgeTrendIndicator: View {
 
 #Preview("Change Indicators") {
     VStack(spacing: 20) {
-        Text(verbatim: "Examples").font(.headline)
+        Text("Examples").font(.headline)
         // 15% increase in views - positive sentiment
         BadgeTrendIndicator(trend: TrendViewModel(currentValue: 115, previousValue: 100, metric: SiteMetric.views))
         // 15% decrease in views - negative sentiment
         BadgeTrendIndicator(trend: TrendViewModel(currentValue: 85, previousValue: 100, metric: SiteMetric.views))
         // 0.1% increase in views - negative sentiment
         BadgeTrendIndicator(trend: TrendViewModel(currentValue: 1001, previousValue: 1000, metric: SiteMetric.views))
 
-        Text(verbatim: "Edge Cases").font(.headline).padding(.top)
+        Text("Edge Cases").font(.headline).padding(.top)
         // No change
         BadgeTrendIndicator(trend: TrendViewModel(currentValue: 100, previousValue: 100, metric: SiteMetric.views))
         // Division by zero (from 0 to 100)
diff --git a/Modules/Sources/JetpackStats/Views/CustomDateRangePicker.swift b/Modules/Sources/JetpackStats/Views/CustomDateRangePicker.swift
@@ -209,7 +209,7 @@ private struct QuickPeriodButtonView: View {
                     .ignoresSafeArea()
 
                 VStack {
-                    Text(verbatim: "Main View")
+                    Text("Main View")
                         .font(.largeTitle)
 
                     Button("Show Date Picker") {
diff --git a/Modules/Sources/Support/UI/FX/ShimmerEffect.swift b/Modules/Sources/Support/UI/FX/ShimmerEffect.swift
@@ -41,30 +41,30 @@ extension View {
 
 #Preview {
     VStack(spacing: 30) {
-        Text(verbatim: "Thinking...")
+        Text("Thinking...")
             .font(.largeTitle)
             .fontWeight(.bold)
             .shimmer()
             .foregroundStyle(.gray)
 
-        Text(verbatim: "Thinking...")
+        Text("Thinking...")
             .font(.title2)
             .fontWeight(.semibold)
             .shimmer()
             .foregroundStyle(.orange)
 
-        Text(verbatim: "Thinking...")
+        Text("Thinking...")
             .font(.body)
             .fontWeight(.bold)
             .shimmer()
             .foregroundStyle(.blue)
 
-        Text(verbatim: "Thinking...")
+        Text("Thinking...")
             .font(.body)
             .shimmer()
             .foregroundStyle(.pink)
 
-        Text(verbatim: "Thinking...")
+        Text("Thinking...")
             .font(.caption)
             .shimmer()
             .foregroundStyle(.green)
diff --git a/Modules/Sources/Support/UI/OverlayProgressView.swift b/Modules/Sources/Support/UI/OverlayProgressView.swift
@@ -93,15 +93,15 @@ struct OverlayProgressView: View {
     NavigationStack {
         List {
             ForEach(0..<12) { i in
-                Text(verbatim: "Row \(i)")
+                Text("Row \(i)")
             }
         }
         .navigationTitle("Demo")
         .toolbar {
             Button {
                 shouldDisplay.toggle()
             } label: {
-                Text(verbatim: "Toggle Progress View")
+                Text("Toggle Progress View")
             }
         }
     }
diff --git a/Modules/Sources/Support/UI/Support Conversations/SupportConversationReplyView.swift b/Modules/Sources/Support/UI/Support Conversations/SupportConversationReplyView.swift
@@ -272,7 +272,7 @@ public struct SupportConversationReplyView: View {
     var isPresented: Bool = true
 
     NavigationStack {
-        Text(verbatim: "Hello World").onTapGesture {
+        Text("Hello World").onTapGesture {
             isPresented = true
         }
     }.sheet(isPresented: $isPresented) {
diff --git a/Modules/Sources/Support/UI/Support Conversations/SupportForm.swift b/Modules/Sources/Support/UI/Support Conversations/SupportForm.swift
@@ -422,7 +422,7 @@ private extension SupportFormArea {
 // MARK: - Previews
 #Preview {
     NavigationStack {
-        Text(verbatim: "Support Form")
+        Text("Support Form")
     }
     .sheet(isPresented: .constant(true)) {
         NavigationStack {
diff --git a/Modules/Sources/WordPressUI/Views/CardView.swift b/Modules/Sources/WordPressUI/Views/CardView.swift
@@ -33,8 +33,8 @@ public struct CardView<Content: View>: View {
 #Preview("With Title") {
     CardView("Section Title") {
         VStack(alignment: .leading, spacing: 12) {
-            Text(verbatim: "Card Content")
-            Text(verbatim: "More content here")
+            Text("Card Content")
+            Text("More content here")
                 .foregroundStyle(.secondary)
         }
     }
@@ -46,7 +46,7 @@ public struct CardView<Content: View>: View {
         HStack {
             Image(systemName: "star.fill")
                 .foregroundStyle(.yellow)
-            Text(verbatim: "Featured Item")
+            Text("Featured Item")
             Spacer()
         }
     }
diff --git a/Modules/Sources/WordPressUI/Views/EmptyStateView.swift b/Modules/Sources/WordPressUI/Views/EmptyStateView.swift
@@ -138,13 +138,13 @@ extension EmptyStateView where Label == SwiftUI.Label<Text, Image>, Description
 
 #Preview("Custom") {
     EmptyStateView {
-        Text(verbatim: "You don't have any tags")
+        Text("You don't have any tags")
     } description: {
-        Text(verbatim: "Tags created here can be easily added to new posts")
+        Text("Tags created here can be easily added to new posts")
     } actions: {
         Button {
         } label: {
-            Text(verbatim: "Create Tag")
+            Text("Create Tag")
         }
         .buttonStyle(.borderedProminent)
     }
diff --git a/Modules/Sources/WordPressUI/Views/InfoRow.swift b/Modules/Sources/WordPressUI/Views/InfoRow.swift
@@ -56,7 +56,7 @@ extension InfoRow where Content == Text {
                 Circle()
                     .fill(.green)
                     .frame(width: 8, height: 8)
-                Text(verbatim: "Active")
+                Text("Active")
                     .foregroundStyle(.green)
             }
         }
@@ -67,7 +67,7 @@ extension InfoRow where Content == Text {
 
         InfoRow("Tags") {
             HStack(spacing: 4) {
-                Text(verbatim: "Swift")
+                Text("Swift")
                 Image(systemName: "chevron.forward")
                     .font(.caption2)
             }
diff --git a/docs/localization.md b/docs/localization.md
@@ -83,20 +83,23 @@ Use `SharedStrings` (@WordPress/Classes/Utility/SharedStrings.swift) for common
 let localizedCount = NumberFormatter.localizedString(from: NSNumber(value: count), number: .none)
 ```
 
-## Non-localizable text and previews
+## Non-localizable text
 
-A SwiftUI `Text("literal")` uses `LocalizedStringKey`, so the literal is **automatically extracted for translation**. For strings that must *not* be translated — glyphs and symbols (`Text("·")`), brand names (`Text("WordPress.com")`), pure interpolations (`Text("@\(username)")`), and any text in `#Preview` / `PreviewProvider` / developer-only screens — use `Text(verbatim:)` so the string is excluded:
+A SwiftUI `Text("literal")` uses `LocalizedStringKey`, so in **shipping code** the literal is **automatically extracted for translation**. For strings that must *not* be translated — glyphs and symbols (`Text("·")`), brand names (`Text("WordPress.com")`), and pure interpolations (`Text("@\(username)")`) — use `Text(verbatim:)` so the string is excluded:
 
 ```swift
 Text(verbatim: "·")                 // divider glyph — not translatable
 Text(verbatim: "WordPress.com")     // brand name — not translatable
-
-#Preview {
-    Text(verbatim: "Sample Card")   // preview placeholder — never ships, must be verbatim
-}
 ```
 
-This is the only opt-out — Apple has no preview- or `#if DEBUG`-specific exclusion. **A localizable `Text("…")` literal inside a `#Preview` or `PreviewProvider` fails CI** (the "Lint SwiftUI Preview Strings" step / `bundle exec fastlane lint_swiftui_preview_strings`); wrap it in `Text(verbatim:)` to fix.
+### Previews and `#if DEBUG` are excluded automatically — don't wrap them
+
+You do **not** need `Text(verbatim:)` for placeholder strings in `#Preview`, `PreviewProvider`, or `#if DEBUG` blocks, and you don't need to flag them in review. The extraction tooling excludes them on its own:
+
+- `xcstringstool extract` tags every extracted string with the compile gate it sits under — its `visibility`. Shipping code carries none (`visibility: nil`); a preview literal comes out as `visibility: "preview"`, and a `#if DEBUG` literal as `visibility: defined(DEBUG)`.
+- `xcstringstool sync` — the step that builds `Localizable.xcstrings` — admits **only** unconditional strings (`visibility: nil`). Anything carrying a `visibility` (preview, `#if DEBUG`, or a combination of the two) is dropped before it can reach the catalog or GlotPress.
+
+So a plain `Text("Sample Card")` inside a `#Preview` is fine as-is — it is not a localization leak, and wrapping it in `verbatim:` only adds noise. If you spot a translatable literal in a preview during review, you can leave it: `sync` already excludes it.
 
 ## Organization Pattern
 
diff --git a/fastlane/lanes/localization.rb b/fastlane/lanes/localization.rb
@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'tmpdir'
-require 'fileutils'
-require 'open3'
-
 #################################################
 # Constants
 #################################################
@@ -594,108 +589,4 @@ def download_localized_app_store_metadata(glotpress_project_url:, locales:, meta
       skip_confirm: skip_confirm
     )
   end
-
-  #################################################
-  # SwiftUI preview-string lint
-  #
-  # Fails if a localizable SwiftUI `Text("…")` literal lives inside a `#Preview` or `PreviewProvider`.
-  # Preview code never ships to users, but Apple's extractor (`xcstringstool extract --SwiftUI-Text`)
-  # still pulls those literals into the String Catalog and feeds them to translators as garbage. The
-  # only correct opt-out is `Text(verbatim:)` (Apple has no preview-specific exclusion).
-  #
-  # This reuses the extractor as its own oracle: `xcstringstool` tags every extracted string's
-  # `visibility`, and preview literals come out as `visibility: "preview"` — so no source parsing or
-  # brace-tracking is required, and the lint is tautologically consistent with what extraction does.
-  #
-  # Scope (validated adversarially — zero false positives, so it never blocks an innocent PR):
-  #   • Catches `Text("…")` written *lexically inside* a `#Preview`/`PreviewProvider` (any nesting depth,
-  #     plus `#if`-gated previews via `preview_visibility?`).
-  #   • Known gaps (by design, not bugs): a preview-only string hoisted into a free helper view/func is
-  #     indistinguishable from shipping code, so it isn't tagged `preview`; and modern localizable APIs
-  #     (`String(localized:)`, `LocalizedStringResource`) aren't on the `--SwiftUI-Text` surface. Both are
-  #     latent today (the cleanup is `Text("…")`-only) — revisit if/when those patterns appear.
-  #################################################
-
-  desc 'Fails if a localizable SwiftUI Text("…") literal lives in a #Preview (use Text(verbatim:) instead)'
-  lane :lint_swiftui_preview_strings do
-    roots = [
-      File.join(PROJECT_ROOT_FOLDER, 'WordPress'),
-      File.join(PROJECT_ROOT_FOLDER, 'Modules', 'Sources')
-    ]
-    files = swiftui_lint_source_files(roots)
-    UI.user_error!('No Swift source files found to lint') if files.empty?
-    UI.message("Scanning #{files.count} Swift files for localizable Text(\"…\") literals in previews…")
-
-    offenders = preview_localizable_text_literals(files)
-
-    if offenders.empty?
-      UI.success('No localizable Text("…") literals found in SwiftUI previews. ✅')
-    else
-      offenders.each { |offender| UI.error("  #{offender}") }
-      UI.user_error!(
-        "#{offenders.count} localizable SwiftUI `Text(\"…\")` literal(s) found in `#Preview` / `PreviewProvider`. " \
-        'Preview strings must not be extracted for translation — wrap each in `Text(verbatim:)`.'
-      )
-    end
-  end
-
-  # Enumerate .swift files under the given roots, applying the same exclusions as the string-extraction flow
-  # (vendored code, the unit-test harness, and AppLocalizedString.swift's own definition).
-  def swiftui_lint_source_files(roots)
-    roots.flat_map { |root| Dir.glob(File.join(root, '**', '*.swift')) }
-         .reject { |path| path.include?('Vendor/') || path.include?('/WordPressTest/') || File.basename(path) == 'AppLocalizedString.swift' }
-         .uniq
-         .sort
-  end
-
-  # Run `xcstringstool extract --SwiftUI-Text` over the files and return a sorted "file:line  \"key\"" entry
-  # for every extracted string tagged `visibility: preview` (i.e. originating from #Preview / PreviewProvider).
-  def preview_localizable_text_literals(files)
-    Dir.mktmpdir do |dir|
-      extract_swiftui_text_stringsdata(files, dir)
-      Dir.glob(File.join(dir, '**', '*.stringsdata')).flat_map { |path| preview_offenders_in(path) }.sort
-    end
-  end
-
-  # Extract `--SwiftUI-Text` .stringsdata for all files into `dir`, chunked to stay under ARG_MAX.
-  # `--omit-empty-stringsdata` skips writing a file per source with no strings.
-  def extract_swiftui_text_stringsdata(files, dir)
-    files.each_slice(400).with_index do |chunk, index|
-      chunk_dir = File.join(dir, "chunk-#{index}")
-      FileUtils.mkdir_p(chunk_dir)
-      _out, err, status = Open3.capture3('xcrun', 'xcstringstool', 'extract', *chunk, '--SwiftUI-Text', '--omit-empty-stringsdata', '--output-directory', chunk_dir)
-      UI.user_error!("xcstringstool extract failed:\n#{err}") unless status.success?
-    end
-  end
-
-  # Parse one .stringsdata (a property list) into "file:line  \"key\"" entries for its preview-visibility strings.
-  # Scans every table (not just Localizable) so a preview using `Text("…", tableName:)` is still caught.
-  def preview_offenders_in(stringsdata_path)
-    json, status = Open3.capture2('plutil', '-convert', 'json', '-o', '-', stringsdata_path)
-    return [] unless status.success?
-
-    data = JSON.parse(json)
-    source = data['source'].to_s.sub("#{PROJECT_ROOT_FOLDER}/", '')
-    (data['tables'] || {}).values.flatten
-      .select { |entry| preview_visibility?(entry['visibility']) }
-      .map { |entry| offender_label(source, entry) }
-  end
-
-  # "file:line  \"key\"" label for a single offending stringsdata entry.
-  def offender_label(source, entry)
-    "#{source}:#{entry.dig('location', 'startingLine')}  #{entry['key'].inspect}"
-  end
-
-  # True if a string's `visibility` denotes a SwiftUI preview. `xcstringstool` emits a bare "preview" for a
-  # plain `#Preview`/`PreviewProvider`, but wraps it when the preview sits under conditional compilation —
-  # e.g. `#if DEBUG` → `#Preview` yields {"type":"conjunction","values":[{"type":"defined","value":"DEBUG"},
-  # "preview"]}. Recurse the values so a `#if DEBUG`-gated preview is caught too. A bare `#if FLAG` (no
-  # preview) is {"type":"defined","value":"FLAG"} with no "preview" leaf, so it stays correctly unflagged.
-  def preview_visibility?(visibility)
-    case visibility
-    when 'preview' then true
-    when Hash then Array(visibility['values']).any? { |value| preview_visibility?(value) }
-    else false
-    end
-  end
 end

Original file line number	Diff line number	Diff line change
`@@ -177,13 +177,13 @@ fileprivate let videoURL = URL(`
`177`	`177`	`CachedAsyncImage(url: testURL) { image in`
`178`	`178`	`image.resizable().scaledToFit()`
`179`	`179`	`} placeholder: {`
`180`		`- Text(verbatim: "Loading")`
	`180`	`+ Text("Loading")`
`181`	`181`	`}`
`182`	`182`	`}`
`183`	`183`
`184`	`184`	`#Preview("Image that never loads") {`
`185`	`185`	`CachedAsyncImage(url: nil) { _ in`
`186`		`- Text(verbatim: "This shouldn't be visible")`
	`186`	`+ Text("This shouldn't be visible")`
`187`	`187`	`} placeholder: {`
`188`	`188`	`ProgressView("Forever loading...")`
`189`	`189`	`}`
`@@ -220,6 +220,6 @@ fileprivate let videoURL = URL(`
`220`	`220`	`CachedAsyncImage(videoUrl: videoURL) { image in`
`221`	`221`	`image.resizable().aspectRatio(contentMode: .fit)`
`222`	`222`	`} placeholder: {`
`223`		`- Text(verbatim: "Loading")`
	`223`	`+ Text("Loading")`
`224`	`224`	`}`
`225`	`225`	`}`
Original file line number	Diff line number	Diff line change
`@@ -93,15 +93,15 @@ struct OverlayProgressView: View {`
`93`	`93`	`NavigationStack {`
`94`	`94`	`List {`
`95`	`95`	`ForEach(0..<12) { i in`
`96`		`- Text(verbatim: "Row \(i)")`
	`96`	`+ Text("Row \(i)")`
`97`	`97`	`}`
`98`	`98`	`}`
`99`	`99`	`.navigationTitle("Demo")`
`100`	`100`	`.toolbar {`
`101`	`101`	`Button {`
`102`	`102`	`shouldDisplay.toggle()`
`103`	`103`	`} label: {`
`104`		`- Text(verbatim: "Toggle Progress View")`
	`104`	`+ Text("Toggle Progress View")`
`105`	`105`	`}`
`106`	`106`	`}`
`107`	`107`	`}`
Original file line number	Diff line number	Diff line change
`@@ -272,7 +272,7 @@ public struct SupportConversationReplyView: View {`
`272`	`272`	`var isPresented: Bool = true`
`273`	`273`
`274`	`274`	`NavigationStack {`
`275`		`- Text(verbatim: "Hello World").onTapGesture {`
	`275`	`+ Text("Hello World").onTapGesture {`
`276`	`276`	`isPresented = true`
`277`	`277`	`}`
`278`	`278`	`}.sheet(isPresented: $isPresented) {`
Original file line number	Diff line number	Diff line change
`@@ -422,7 +422,7 @@ private extension SupportFormArea {`
`422`	`422`	`// MARK: - Previews`
`423`	`423`	`#Preview {`
`424`	`424`	`NavigationStack {`
`425`		`- Text(verbatim: "Support Form")`
	`425`	`+ Text("Support Form")`
`426`	`426`	`}`
`427`	`427`	`.sheet(isPresented: .constant(true)) {`
`428`	`428`	`NavigationStack {`
Original file line number	Diff line number	Diff line change
`@@ -33,8 +33,8 @@ public struct CardView<Content: View>: View {`
`33`	`33`	`#Preview("With Title") {`
`34`	`34`	`CardView("Section Title") {`
`35`	`35`	`VStack(alignment: .leading, spacing: 12) {`
`36`		`- Text(verbatim: "Card Content")`
`37`		`- Text(verbatim: "More content here")`
	`36`	`+ Text("Card Content")`
	`37`	`+ Text("More content here")`
`38`	`38`	`.foregroundStyle(.secondary)`
`39`	`39`	`}`
`40`	`40`	`}`
`@@ -46,7 +46,7 @@ public struct CardView<Content: View>: View {`
`46`	`46`	`HStack {`
`47`	`47`	`Image(systemName: "star.fill")`
`48`	`48`	`.foregroundStyle(.yellow)`
`49`		`- Text(verbatim: "Featured Item")`
	`49`	`+ Text("Featured Item")`
`50`	`50`	`Spacer()`
`51`	`51`	`}`
`52`	`52`	`}`