[Resources] Support prioritized locale fallback chain for resources (CMP-6840)

[Abhishek Keshri (2KAbhishek)]

Description

Resolves CMP-6840 by supporting prioritized multi-locale resource matching across all platforms.

Previously, resource matching evaluated only a single platform locale. If an application provided resources in Spanish (values-es/) but not French, a bilingual user preferring French then Spanish ([fr, es]) received the default values/ folder instead of their second-preference Spanish. Furthermore, platforms reported only a single preferred locale to Compose.

Key Changes & Design Considerations

1. Prioritized Multi-Locale Matching:

   • Evaluates the ordered list of user locales against available resources following the multi-locale resolution sequence (as in Table 3 of Android's Multilingual Support guide).
   • Supports same-language region fallback (e.g., fr-CH $\rightarrow$ fr-FR). To avoid bundling heavy CLDR distance tables across KMP targets, CMP uses deterministic alphabetical selection (.minOrNull()) when multiple alternate regions are available.
   • Prohibits cross-script substitution for Chinese (zh-Hans / zh-CN never substitutes for zh-Hant / zh-TW), covering both region-qualified and script-qualified folders (values-b+zh+Hans/). Explicit script qualifiers are respected across all languages.

2. Full Preferred Locale Reporting Across Platforms:

   • Android: Reads LocaleList.getDefault(), respecting per-app language settings and Android 13+ app locales.
   • Apple: Reads NSLocale.preferredLanguages directly (retaining region and script qualifiers without Xcode bundle filtering).
   • Web (JS/Wasm): Reads navigator.languages.
   • Desktop (JVM): Queries the system preferred language list via Windows registry (HKCU\Control Panel\International\User Profile), macOS (/usr/bin/defaults read -g AppleLanguages), or POSIX environment variables (LANGUAGE, LC_ALL, LANG), with a 2-second timeout and lazy single-instance caching. Falls back safely to Locale.getDefault() if subprocess execution is restricted (e.g., sandboxed macOS environments).
   • Retains androidx.compose.ui.text.intl.LocaleList.current at the head of the chain when set (preserving explicit app overrides like Locale.setDefault).

3. Base Language Convention for Unqualified Resources:

   • By convention in Compose Multiplatform, composeResources/values/ represents the base development language (English by default).
   • When evaluating English without an explicit values-en/ directory, unqualified values/ resources satisfy unregionalized English candidates. This ensures bilingual English users (e.g., [en-US, es-US]) receive base English rather than unintentionally skipping to a secondary language override.
   • Explicit values-en/ and regional values-en-rXX/ folders continue to take strict precedence when provided.

4. Resource-Aware Pluralization:

   • Evaluates plural categories using the locale of the matched resource item rather than the user's primary preference. Unqualified resources default to English plural rules.

5. API Stability:

   • Synced desktop and KLib API dumps (apiDump) for the @InternalResourceApi data class LocaleQualifiers addition.

Fixes CMP-6840

Testing

Run from the components directory:

./gradlew :resources:library:desktopTest \
  :resources:library:testAndroidHostTest \
  :resources:library:compileKotlinJs \
  :resources:library:compileKotlinWasmJs

• Added comprehensive unit tests in ResourceTest covering multi-locale fallback chains, regional fallback, script mismatch isolation, pluralization locale selection, and unqualified resource precedence.
• Verified test suites on :resources:library:desktopTest and :resources:library:testAndroidHostTest.
• Verified multiplatform compilation across iOS, macOS, JS, and WasmJS targets.

Release Notes

Fixes - Resources

• Resources are matched against the user's full list of preferred languages instead of only the first one, so a language further down the list is used when preceding languages have no matching resources
  • A locale falls back to another region of the same language (e.g., fr-CH uses values-fr-rFR). Script compatibility is strictly enforced so zh-Hans never matches values-zh-rTW
  • Unqualified values/ resources satisfy base English when no explicit values-en/ folder exists, preventing bilingual users with English as a primary preference from unintentionally falling back to secondary language overrides
  • Plural categories follow the language of the matched resource rather than the primary device preference
  • Per-app language settings are respected on Android, and the system preference list is read on Desktop instead of the single JVM default locale

Note: AI assistance was used for this PR

[Abhishek Keshri (2KAbhishek)]

Hi Konstantin (@terrakok)

I have raised a fix for https://youtrack.jetbrains.com/issue/CMP-6840 here and was hoping to get your feedback, can you please take a look when you have a chance 🙏🏽

If you think I should reach out to someone else please let me know, Thank you

[Konstantin (terrakok)]

It is already WIP: #5759

[Konstantin (terrakok)]

(and next time, please, don't send as AI slop PRs)