feat: localisation for Dynamic Widgets and Dynamic Live Activities

[V3RON]

What is this?

Dynamic Widgets and Dynamic Live Activities can now be translated and formatted for the person looking at them, on iOS and Android, from the same JavaScript that draws them. Until now a widget author had env.locale and little else, and on iOS that value was not usable: it arrived as pl_PL, which Intl rejects with a RangeError, and it followed whichever languages happened to have a translated gallery label rather than the languages the app supports. Android widgets kept their old language after the user changed it, and several Intl APIs that i18n libraries depend on are missing there.

This lands ADR 0009, which records the investigation, the platform facts behind each decision, and the device tests (T1 to T7) that gate the release. Both platforms were exercised with the example app: an iOS 18.0 simulator and an API 36 emulator. Locale environment, system language change with the app not running, per-app language, setDynamicWidgetLocale with a running Live Activity, RTL, the translated Edit Widget sheet and the generated Android resources all behaved as documented. Swift and Kotlin were not compiled in the authoring environment; CI covers that.

How does it work?

• A complete locale environment on both platforms. env.locale is a BCP-47 tag on iOS too, and both platforms add preferredLanguages, appLocale, layoutDirection, hourCycle (matching the user's 12/24-hour setting), timeZone, measurementSystem, calendar and firstDayOfWeek. Live Activities receive the same fields.
• Widgets render again when the language changes. iOS does this on its own. On Android, placed widgets now render again after a device, per-app or regional language change, even with the app not running, and at once while it is. The reload advances each placement's Glance revision first, because update on a session that is still open (45 seconds after a render) recomposes nothing otherwise.
• setDynamicWidgetLocale(tag | null) on both clients lets an app with its own language picker choose the widget language. It reaches every render as env.appLocale; widgets and running Live Activities render again immediately. It changes the translation only; the formatting fields and layout direction keep following locale. On iOS it needs groupIdentifier.
• Widgets declare the app's languages on iOS, from the Expo locales config, CFBundleLocalizations, widget locale maps and the app's development language, so env.locale resolves to the language the app runs in.
• resolveLocale(env, messages) and pickLocalizedValue move to @use-voltra/core and are exported from @use-voltra/ios and @use-voltra/android, with the same fallback order as localized initial states.
• Android Intl gaps are covered by an opt-in withVoltra(config, { androidIntlPolyfills }) option that adds the FormatJS polyfills to Android widget bundles only.
• The Edit Widget sheet can be translated. appIntent.parameters[].title accepts locale maps, and parameters accept static options, shown as a picker on iOS. The sheet header is the widget's displayName, which the existing locale map already translates. Android stores the same strings as resources for an in-app configuration screen. The CLI mirrors all of it.
• New Localization pages for iOS and Android, updated Dynamic Widgets, Configurable Widgets, Live Activities and plugin configuration pages, and changesets.

Why is this useful?

One JavaScript entry now renders correctly in every language and format the device is set to, with no per-language bundles, no native string tables for widget content, and no stale widgets after a language change. The two surfaces the operating system draws itself, the gallery and the Edit Widget sheet, are translated from the same app.json locale maps.