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")` now 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"`. No source parsing
or brace-tracking, and tautologically consistent with what extraction pulls.
Self-contained (no dependency on the #25688 catalog lane). Green on the current
tree; verified it fails on an injected preview literal.

Documents the `verbatim:` rule and the gate in docs/localization.md.

Author: jkmassel

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

@@ -0,0 +1,7 @@
+#!/bin/bash -eu
+
+echo "--- :rubygems: Setting up Gems"
+install_gems
+
+echo "--- :sleuth_or_spy: Linting SwiftUI preview strings"
+bundle exec fastlane lint_swiftui_preview_strings

.buildkite/pipeline.yml

@@ -130,6 +130,13 @@ steps:
         command: .buildkite/commands/lint-localized-strings-format.sh
         plugins: [$CI_TOOLKIT_PLUGIN]
 
+      - 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
 #################################################
@@ -567,4 +572,76 @@ 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.
+  #################################################
+
+  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|
+      # Chunked to stay under ARG_MAX; `--omit-empty-stringsdata` skips writing a file per source with no strings.
+      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
+
+      Dir.glob(File.join(dir, '**', '*.stringsdata')).flat_map do |path|
+        # .stringsdata is a property list on disk; convert to JSON to read it.
+        json, status = Open3.capture2('plutil', '-convert', 'json', '-o', '-', path)
+        next [] unless status.success?
+
+        data = JSON.parse(json)
+        source = data['source'].to_s.sub("#{PROJECT_ROOT_FOLDER}/", '')
+        # Scan every table (not just Localizable) so a preview using `Text("…", tableName:)` is still caught.
+        (data['tables'] || {}).values.flatten
+          .select { |entry| entry['visibility'] == 'preview' }
+          .map { |entry| "#{source}:#{entry.dig('location', 'startingLine')}  #{entry['key'].inspect}" }
+      end.sort
+    end
+  end
 end