Localization: stage translations into the String Catalog (manual)

[jkmassel]

Fills the app's String Catalog (Localizable.xcstrings) with translations — the human translations we already have from GlotPress, plus machine translations for whatever is still untranslated. This gets the catalog ready ahead of moving the app over to String Catalogs. Nothing users see changes.

Two things to know

Staged, not shipped. The catalog file is generated, but the app doesn't read it at runtime yet — regular strings still come from the existing Localizable.strings. This only pre-fills the catalog for the eventual switch-over. Machine translations are marked needs_review, so they stay clearly separate from reviewed human translations and can sit in the catalog without shipping to anyone.

Manual, not automated. These lanes are run by hand, not wired into any release or CI step: a run extracts strings, calls a paid translation API, and commits a large file, so it shouldn't happen on its own. The unit tests still run in CI.

How it works

Three steps, each runnable on its own:

1. generate_strings_catalog — extracts the English strings from the code into the catalog.
2. download_catalog_strings — downloads the current translations from GlotPress.
3. localize_catalog — adds the human translations, machine-translates whatever's left, and commits.

Each string gets the best translation available in each language: a human translation if there is one, otherwise a machine translation, otherwise the English text. Human translations are marked translated; machine translations and English fallbacks are marked needs_review.

Re-running is cheap. A machine translation already in the catalog is left alone instead of being requested again, and a human translation always replaces a machine one on the next run. Machine translation only happens when an API key is set — without one, the catalog fills from human translations and English. A machine translation is kept only if its format placeholders (%1$@, %2$d, …) match the English, so a mangled one falls back to English rather than shipping a broken string.

Test plan

• Unit tests pass (fastlane/lanes/*_test.rb) — these run in CI
• rubocop clean
• Manual run against live GlotPress data (steps below)

Manual run

First bundle install. A machine-translation run also needs an ANTHROPIC_API_KEY — the Fastfile picks it up from ~/.wpios-env.default. Without a key the run still works: it fills in the human translations and English only, skips machine translation, and costs nothing — a good way to check the plumbing before spending anything.

Run the three lanes, scoped to one well-translated locale to keep it cheap:

bundle exec fastlane ios generate_strings_catalog
bundle exec fastlane ios download_catalog_strings locales:fr
bundle exec fastlane ios localize_catalog locales:fr

1. generate_strings_catalog extracts the English strings into Localizable.xcstrings (~3,900 of them). No network, no cost.
2. download_catalog_strings downloads the French translations from GlotPress into a scratch folder. No cost.
3. localize_catalog fills the French translations into the catalog, machine-translates the gaps, and commits.

French is well-translated, so most entries come from GlotPress and only a small number fall to machine translation, which keeps the cost for one locale low. A few entries may stay English where a machine translation was rejected for not matching the English placeholders.

localize_catalog prints a per-locale summary at the end, so you can check the result straight from the log — no need to open the catalog:

fr: 3923 entries — 3805 human, 112 machine, 6 still English
    editor.post.delete: "Delete" → "Supprimer"
    settings.title: "Settings" → "Réglages"

Expect mostly human, a smaller machine count, and only a few still English. The sample lines let you spot-check the machine translations for obvious nonsense.

localize_catalog commits the catalog, which is a large file. This run is only to check the output and cost, so discard the commit rather than pushing it (git reset --hard HEAD~1). The catalog gets committed for real during the migration, not in this PR.

Plurals are handled the same way in a separate PR (#25710), since they live in their own catalog file.

[dangermattic]

	2 Warnings
⚠️	This PR is larger than 500 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.
⚠️	This PR is assigned to the milestone 27.1. This milestone is due in less than 4 days. Please make sure to get it merged by then or assign it to a milestone with a later deadline.

Generated by 🚫 Danger

[oguzkocer]

I've completed my first pass on this and found one issue reported by Claude and opened a PR to add a couple failing tests for it: #25802

I didn't see anything in my manual review, but I also haven't spent a significant time on it yet. If it's not reviewed by anyone else, I'll pick this up again once #25802 is addressed.

[jkmassel]

@oguzkocer – I fixed that issue (and a couple of related ones) in #25802 then landed it into this PR.

[mokagio]

These are now green, I think. https://buildkite.com/automattic/wordpress-ios/builds/33234/canvas?jid=019f778c-7142-4c96-8103-a67d788ee4c4&tab=output

[mokagio]

I asked Opus 4.8 for help in reviewing this PR. Of the various points it raised, the one that stood out to me regards the consequences of a no-API-key run.

Implicit tradeoff: the fold materializes a cell for every (key, locale) pair — 141,240 cells, ~22 MB committed — and the "still English" count in the run summary is derived from those materialized cells rather than computed. So the storage decision and the reporting decision are silently coupled, and nothing in the PR says so.

Where it bites today: the no-API-key run the PR recommends as the cheap plumbing check writes 141,240 English-fallback cells and commits 21.5 MB of zero-information JSON. In the intended mode (AI on) this is a non-issue — English fallbacks drop to zero.

Suggestion: don't commit when the AI tier is disabled (or warn loudly), and make summarize derive english: as translatable_total − human − machine so a future prune of English-fallback cells doesn't silently zero out that number.

ai_translator = catalog_ai_translator
written = CatalogStrings.fold_translations!(catalog, ..., ai_translator: ai_translator)
...
if ai_translator.nil? && options[:commit].to_s != 'true'
  UI.important('Skipping the commit: no AI tier, so every gap cell is an English placeholder. ' \
               'Re-run with ANTHROPIC_API_KEY set, or pass commit:true to stage the human-only fold.')
  next
end

git_add(path: LOCALIZABLE_CATALOG, shell_escape: false, force: true)
git_commit(...)