Localization: fail CI when a localizable Text("…") lives in a #Preview

Adds a `lint_swiftui_preview_strings` fastlane lane and a "Lint SwiftUI Preview
Strings" Buildkite step so preview strings can't regress: a `#Preview` shipping a
translatable `Text("literal")` fails CI with the exact file:line and the fix
(wrap in `Text(verbatim:)`).

Reuses Apple's extractor as its own oracle — `xcstringstool extract --SwiftUI-Text`
tags every extracted string's `visibility`, and #Preview / PreviewProvider
literals come out as `visibility: "preview"` (recursing the compound value so
`#if DEBUG`-gated previews are caught too). No source parsing or brace-tracking,
and tautologically consistent with what extraction pulls. Self-contained (no
dependency on the #25688 catalog lane); validated adversarially with zero false
positives. Documents the `verbatim:` rule and the gate in docs/localization.md.

Author: jkmassel

.buildkite/commands/lint-swiftui-preview-strings.sh

@@ -0,0 +1,13 @@
+#!/bin/bash -eu
+
+echo "--- :rubygems: Setting up Gems"
+install_gems
+
+# The Fastfile `before_all` hook requires project.env to exist; the example copy is enough for this lint
+# (it reads no secrets — only source files + xcstringstool).
+echo "--- :writing_hand: Copy Files"
+mkdir -pv ~/.configure/wordpress-ios/secrets
+cp -v fastlane/env/project.env-example ~/.configure/wordpress-ios/secrets/project.env
+
+echo "--- :sleuth_or_spy: Linting SwiftUI preview strings"
+bundle exec fastlane lint_swiftui_preview_strings

.buildkite/pipeline.yml

@@ -163,6 +163,13 @@ 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
   #################

docs/localization.md

@@ -83,6 +83,21 @@ Use `SharedStrings` (@WordPress/Classes/Utility/SharedStrings.swift) for common
 let localizedCount = NumberFormatter.localizedString(from: NSNumber(value: count), number: .none)
 ```
 
+## Non-localizable text and previews
+
+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:
+
+```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.
+
 ## Organization Pattern
 
 Organize strings using private enums within each view or view model:

fastlane/lanes/localization.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+require 'open3'
+
 #################################################
 # Constants
 #################################################
@@ -589,4 +594,108 @@ 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