Restructure download_localized_catalog into explicit scan -> download -> AI-fill

Make the lane mirror the pipeline order: (1) generate_strings_catalog scans the code, (2) it
now downloads the current GlotPress translations itself (ios_download_strings_files_from_glotpress)
and folds them in, (3) CatalogStrings AI-fills the rest. Adds a locales:fr,de scope (and
skip_download:true) so a run can be kept cheap. Uploading the AI drafts back to GlotPress
(the eventual step 4) stays out — it builds on the existing GlotPress import integration
(gp_update_metadata_source), not done here.

Author: jkmassel

fastlane/lanes/localization_catalog.rb

@@ -82,29 +82,42 @@
     end
   end
 
-  # Folds the downloaded GlotPress translations (human) plus AI machine translations into Localizable.xcstrings,
-  # the future regular-string backing store, as `human ?? existing-machine ?? AI ?? English` (see CatalogStrings).
+  # Builds Localizable.xcstrings, the future regular-string backing store, end to end:
+  #   1. scan the code into the English catalog (generate_strings_catalog),
+  #   2. download the current GlotPress translations and fold them in (human => translated),
+  #   3. AI-fill the cells GlotPress left empty (=> needs_review) — see CatalogStrings.fold_translations!.
+  # Uploading the AI drafts back to GlotPress as needs-review for human review (the eventual "step 4") is a
+  # separate step, not done here — it builds on the existing GlotPress import integration (cf.
+  # gp_update_metadata_source). For now the machine cells live in the catalog as needs_review.
   #
-  # STAGED, NOT SHIPPED: the catalog isn't the runtime store yet (the app still ships Localizable.strings), so
-  # this only pre-populates it for the eventual cutover — it changes nothing users see.
+  # STAGED, NOT SHIPPED: Localizable.xcstrings isn't the runtime store yet (the app still ships
+  # Localizable.strings), so this only pre-populates it for the cutover — it changes nothing users see.
   #
-  # MANUAL ONLY — deliberately NOT wired into download_localized_strings or any CI step: it runs xcstringstool
-  # extraction, calls the translation API (cost), and commits a large catalog, so it's run on demand, not on
-  # every release. Run `download_localized_strings` first (so the per-locale `.strings` exist) and, for the AI
-  # rung, set ANTHROPIC_API_KEY.
-  desc 'Folds GlotPress + AI translations into Localizable.xcstrings (staged backing store; run manually, not in CI)'
-  lane :download_localized_catalog do
-    generate_strings_catalog # refresh the English source + reconcile (creates the catalog on first run)
-    catalog = JSON.parse(File.read(LOCALIZABLE_CATALOG))
+  # MANUAL ONLY — deliberately not wired into download_localized_strings or any CI step: it runs xcstringstool
+  # extraction, downloads from GlotPress, calls the translation API (cost), and commits a large catalog. Set
+  # ANTHROPIC_API_KEY for step 3; scope a cheap run with `locales:fr` (and add `skip_download:true` to reuse the
+  # committed .strings instead of re-downloading).
+  desc 'Builds Localizable.xcstrings: scan code, fold GlotPress translations, AI-fill the rest (staged; manual, not CI)'
+  lane :download_localized_catalog do |options|
+    resources_dir = File.join(PROJECT_ROOT_FOLDER, 'WordPress', 'Resources')
+    locales = catalog_target_locales(options[:locales]) # all ship locales, or the `locales:fr,de` subset
+
+    # 1. Scan the code into the English catalog (create / update + reconcile changed sources).
+    generate_strings_catalog
+
+    # 2. Download the current GlotPress translations for those locales (skip to reuse the committed .strings).
+    download_catalog_strings(resources_dir, locales) unless catalog_flag?(options[:skip_download])
 
+    # 2b + 3. Fold the human translations in (=> translated), then AI-fill the cells GlotPress left empty.
+    catalog = JSON.parse(File.read(LOCALIZABLE_CATALOG))
     written = CatalogStrings.fold_translations!(
       catalog,
-      translations_by_locale: catalog_translations_by_locale(File.join(PROJECT_ROOT_FOLDER, 'WordPress', 'Resources')),
-      locales: GLOTPRESS_TO_LPROJ_APP_LOCALE_CODES.values.uniq,
+      translations_by_locale: catalog_translations_by_locale(resources_dir),
+      locales: locales.values.uniq,
       ai_translator: catalog_ai_translator
     )
     File.write(LOCALIZABLE_CATALOG, "#{JSON.pretty_generate(catalog)}\n")
-    UI.success("Folded translations into #{File.basename(LOCALIZABLE_CATALOG)} (#{written} cells across locales).")
+    UI.success("Built #{File.basename(LOCALIZABLE_CATALOG)}: folded #{written} cell(s) across #{locales.values.uniq.size} locale(s).")
 
     git_add(path: LOCALIZABLE_CATALOG, shell_escape: false)
     git_commit(path: [LOCALIZABLE_CATALOG], message: 'Update Localizable.xcstrings translations (staged)', allow_nothing_to_commit: true)
@@ -229,6 +242,31 @@ def report_catalog(path, extracted_count:, reconciled_count:)
     UI.success(message)
   end
 
+  # The { glotpress => lproj } locale map to operate on: all ship locales, or the subset named in `locales:`
+  # (a comma-separated list of lproj codes, e.g. `locales:fr,de`) for a cheap scoped run.
+  def catalog_target_locales(spec)
+    return GLOTPRESS_TO_LPROJ_APP_LOCALE_CODES if spec.to_s.strip.empty?
+
+    wanted = spec.to_s.split(',').map(&:strip)
+    selected = GLOTPRESS_TO_LPROJ_APP_LOCALE_CODES.select { |_glotpress, lproj| wanted.include?(lproj) }
+    UI.user_error!("No known ship locales among #{spec.inspect} (use lproj codes, e.g. fr,de,pt-BR)") if selected.empty?
+    selected
+  end
+
+  # Step 2: download the current GlotPress translations for the given locales into their `*.lproj` dirs.
+  def download_catalog_strings(resources_dir, locales)
+    ios_download_strings_files_from_glotpress(
+      project_url: GLOTPRESS_APP_STRINGS_PROJECT_URL,
+      locales: locales,
+      download_dir: resources_dir
+    )
+  end
+
+  # A fastlane CLI flag, which arrives as a string ("true"/"1"/"yes") or a real boolean.
+  def catalog_flag?(value)
+    %w[true 1 yes].include?(value.to_s.strip.downcase)
+  end
+
   # { lproj => { key => human value } } from the downloaded translation `.strings`. The flat plural keys present
   # in these files aren't catalog keys, so the fold ignores them (they belong to Plurals.xcstrings).
   def catalog_translations_by_locale(dir)