fix(ios)!: localize the patterns count and let hosts fall back to editor strings

[dcalhoun]

What?

Localizes the patterns count string, and lets host apps fall back to the editor's own strings for keys they do not translate.

Warning

Source-breaking for host apps. EditorLocalization.localize now returns String? instead of String, so every host that assigns it needs a signature update — independent of the new patternsCount(Int) case, which also stops an exhaustive switch from compiling. WordPress-iOS needs a companion PR before it can adopt this version: wordpress-mobile/WordPress-iOS#25848

Why?

The patterns count rendered as a hardcoded English string. Fixing that means adding a case to EditorLocalizableString, which exposed a design problem worth fixing in the same change.

Hosts override EditorLocalization.localize by replacing the closure, so they switch over the enum exhaustively with no default:. Swift requires that switch to be exhaustive, so every string the editor adds breaks the host build — and the break surfaces later, when the host bumps the dependency, not when the string is added. A host that does nothing gets a build failure rather than an untranslated string, which blocks them from adopting unrelated fixes until someone writes a translation.

That penalty is disproportionate for this localization gap. Android string resources fall back through values-ar/ → values/, and gettext returns the source English when no translation exists; neither fails the build. The editor's own JS translations already work this way.

How?

Declining a key — localize returns String?. A host returns nil for keys it does not translate, and the editor supplies its own string:

EditorLocalization.localize = { key in
    switch key {
    case .showMore: NSLocalizedString("editor.blockInserter.showMore", ...)
    // ...keys the host translates.
    @unknown default: nil
    }
}

Once a host writes that fallback case, future keys render untranslated instead of failing to compile.

An optional return rather than a public fallback function the host calls itself, so the fallback cannot be skipped or reimplemented: nil is the only way to decline, and it routes through the editor's defaults and reporting. Every read goes through the EditorLocalization[...] subscript, which unwraps, falls back, and reports in one place.

Reporting — falling back logs each untranslated string once per process, at notice so it persists to the log store without the host configuring EditorLogger. Reporting once per key matters because every call site sits in a SwiftUI body that re-evaluates on each render pass; logging per read would write an entry per row per frame while a list scrolls. Keys are deduplicated by case name, so patternsCount(3) and patternsCount(7) count as one missing string.

Only a nil return reports. The default closure answers every key, so strings the editor reads while building views — loadingEditor among them, which can run before the host assigns localize — are never reported as missing.

Hosts that render the editor's own strings deliberately can opt out with EditorLocalization.reportsMissingTranslations = false.

Isolation — @MainActor sits on localize and the subscript rather than the whole class. localize holds a non-Sendable closure and the subscript reads it; nothing else needs isolation, and no annotation is forced onto host code. Verified with swiftc -typecheck -swift-version 6 -strict-concurrency=complete against a file reproducing WordPress-iOS's call pattern, including that reads off the main actor are still rejected.

Testing Instructions

This is not testable in the Demo app. See testing instructions in wordpress-mobile/WordPress-iOS#25848.

Accessibility Testing Instructions

No UI changes. Strings that previously rendered in English still do; the change is which code supplies them.

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/569")

_{Built from 7b48e6d}

[crazytonyli]

Should EditorLocalization.localize allow returning a nil, which means GBK can call defaultLocalize internally, rather than requiring the app to call it?

[dcalhoun]

This approach makes sense. Thanks for the suggestion. Addressed in 42b4bb4.

[crazytonyli]

Majority of this class are nonisolated functions. Should it be bound to the main actor at all?

[dcalhoun]

I believe I refactored the class to align with your suggestion, but let me know if I did not. See b08789c.

[crazytonyli]

I think you should be able to delete the nonisolated declarations now.

[dcalhoun]

I believe the only remaining nonisolated is with reportsMissingTranslations. When removing it, I see an error: Static property 'reportsMissingTranslations' is not concurrency-safe because it is nonisolated global shared mutable state.

Should this be removable or are you referencing other declarations?

[crazytonyli]

I feel like adding this lock increases complexity. I don't think it's too much to log missing translations repeatedly on the same keys.

[dcalhoun]

I agree there is definitely increased complexity to achieve de-duping logs. I attempted simplifying it in b681e10. Let me know what you think of the state of it now.

I agree losing de-duping is likely not a big issue. The one outlier is the Patterns sheet, where a single missing translation string would result in numerous logs as you scroll the sheet. However, if you feel it's still worth dropping the de-duping entirely, let me know, I'm open to that.