fix: resolve in-app language switching issue in release build

Author: nagarjunavs

CHANGELOG.md

@@ -6,6 +6,27 @@ with the `0.1.0` release.
 
 ## [Unreleased]
 
+### Fixed
+
+- Sample app: changing the app's language via **Settings → Apps → TapSense → Language** (the
+  Android 13+ per-app language picker, wired by `android:localeConfig`/`locales_config.xml`)
+  had no effect in the Play-installed release build (versionCode 5), while the same switch
+  worked immediately in a sideloaded debug build. Root cause: an Android App Bundle splits
+  resources by language into separate install-time delivery APKs by default, so a device only
+  gets the one locale split matching its language at install time; Play is supposed to fetch the
+  rest on demand when the in-app language is changed, but that on-demand delivery proved
+  unreliable, silently leaving the app on its originally-installed locale. Confirmed via `aapt2
+  dump` that every translated string and the `locales_config.xml` resource itself were fully
+  intact in the release APK/AAB - shrinking/minification was never the cause. Fixed by setting
+  `bundle { language { enableSplit = false } }` in `app/build.gradle.kts`, which is Android's own
+  documented remedy for apps whose language can change independent of the system locale
+  (https://developer.android.com/guide/app-bundle/configure-base): every install now packages
+  all locale resources into the base module instead of relying on Play's on-demand split
+  delivery. Verified by decoding the rebuilt `.aab`'s `BundleConfig.pb`, which now carries
+  `SplitDimension{value: LANGUAGE, negate: true}`. Trade-off accepted: a small increase in
+  download size for every install (translated strings only, no additional media/assets) in
+  exchange for reliable in-app language switching.
+
 ## [0.2.0] - 2026-09-02
 
 ### Changed

DECISIONS.md

@@ -83,9 +83,28 @@ same set most apps cover in a first localization pass. Locale selection is Andro
 resource resolution: `values-<lang>/strings.xml` is picked automatically from the device's
 locale on every API level, no code required. `android:localeConfig` (`AndroidManifest.xml` +
 `res/xml/locales_config.xml`) additionally declares these locales for the Android 13+ per-app
-language picker and Play's per-locale APK splits - purely additive, ignored on minSdk 26 through
-32 (`tools:targetApi="33"` on the attribute documents this instead of suppressing the lint
-warning blindly). `app_name` is `translatable="false"`: a brand name, kept identical everywhere.
+language picker - purely additive, ignored on minSdk 26 through 32 (`tools:targetApi="33"` on the
+attribute documents this instead of suppressing the lint warning blindly). `app_name` is
+`translatable="false"`: a brand name, kept identical everywhere.
+
+Play's per-locale App Bundle splitting is deliberately **disabled**
+(`bundle { language { enableSplit = false } }`, `app/build.gradle.kts`), not left on its default.
+The per-app language picker above lets a user select a language independent of the device's
+system locale - exactly the case Android's own App Bundle docs flag as needing this setting
+(https://developer.android.com/guide/app-bundle/configure-base): with splitting left on, Play
+installs only the one locale split matching the device's language at install time and is
+supposed to fetch the rest on demand when the in-app language changes, but that on-demand
+delivery proved unreliable in practice - a versionCode 5 closed tester found that switching
+languages via Settings → Apps → TapSense → Language did nothing on the Play-installed release,
+while the identical switch worked immediately on a sideloaded debug build (which, being a single
+monolithic APK, never depended on split delivery). Confirmed via `aapt2 dump` that the
+versionCode 5 release APK's resources, `locales_config.xml`, and every translation were fully
+intact - shrinking/minification was never the cause, only the App Bundle's language-split
+delivery was. Fixed in versionCode 6 by disabling the split, so every install now bundles every
+locale's resources in the base module instead of depending on Play to deliver the rest later.
+The trade-off is a small download-size increase for every install (translated strings only, no
+additional media) - accepted as worth it for reliable in-app language switching; this is a
+supported Gradle configuration choice, not a Play Store policy concern in either direction.
 
 Arabic/Hebrew (RTL) is deliberately not included in this pass. Translating strings is safe and
 mechanically verifiable (lint's `MissingTranslation`/`ExtraTranslation`/`StringFormatMatches`

app/build.gradle.kts

@@ -27,7 +27,7 @@ android {
         applicationId = "com.tapsense.app"
         minSdk = 26
         targetSdk = 36
-        versionCode = 5
+        versionCode = 6
         versionName = "1.0.0"
 
         testInstrumentationRunner = "com.tapsense.app.HiltTestRunner"
@@ -90,6 +90,21 @@ android {
         }
     }
 
+    // Play's per-language APK-split delivery (the default for an App Bundle) only installs the
+    // locale split matching the device's language at install time, then is supposed to fetch the
+    // rest on demand when the user later changes the per-app language in Settings > Apps >
+    // TapSense > Language. That on-demand fetch is unreliable in practice (confirmed on the
+    // versionCode 5 closed test: switching language did nothing in the Play-installed release,
+    // while a sideloaded debug APK - which always bundles every locale - worked immediately).
+    // Disabling the split ships every locale's resources in the base module on every install, so
+    // the zero-code resource resolution `locales_config.xml` documents always finds the strings
+    // locally instead of depending on Play to deliver them.
+    bundle {
+        language {
+            enableSplit = false
+        }
+    }
+
     lint {
         warningsAsErrors = false
         abortOnError = true

docs/play-store/CHECKLIST.md

@@ -17,7 +17,7 @@ claim; anything not yet decided is marked **TODO (owner)**.
       `BuildConfig.VERSION_NAME`/Settings → About (`"1.0.0-debug"` vs. release's plain `"1.0.0"`)
       — so a tester's screenshot or a local dev's screen share is unambiguous about which build
       they're looking at.
-- [x] `versionCode`/`versionName` present (currently `5` / `"1.0.0"` — check `app/build.gradle.kts`
+- [x] `versionCode`/`versionName` present (currently `6` / `"1.0.0"` — check `app/build.gradle.kts`
       for the live values, since this line goes stale the moment either is bumped and isn't
       re-verified automatically). Convention for this repo: `versionCode` is a plain incrementing
       integer bumped for *every* build uploaded to any Play track (closed testing included) —
@@ -145,7 +145,20 @@ claim; anything not yet decided is marked **TODO (owner)**.
       Arabic/Hebrew (RTL) is deliberately deferred rather than shipped untested.
 - [x] Locale selection is automatic: Android resolves `values-<lang>/` from the device locale on
       every API level, no code required. `android:localeConfig` additionally wires the Android
-      13+ per-app language picker and Play's per-locale APK splits (`res/xml/locales_config.xml`).
+      13+ per-app language picker (`res/xml/locales_config.xml`).
+- [x] Play's per-locale App Bundle splits are **disabled**
+      (`bundle { language { enableSplit = false } }` in `app/build.gradle.kts`), not left on the
+      default. versionCode 5 shipped with the default (split) behavior, and a closed tester found
+      that switching languages via Settings → Apps → TapSense → Language did nothing on the
+      Play-installed build, because Play only installs the one locale split matching the device's
+      language and its on-demand delivery of the rest proved unreliable — confirmed not a
+      shrinking/minification issue via `aapt2 dump` on the versionCode 5 APK. Fixed in versionCode
+      6 per Android's own documented guidance for apps with independent-of-system-locale language
+      switching (https://developer.android.com/guide/app-bundle/configure-base); every install
+      now bundles all locale resources, trading a small download-size increase for reliable
+      switching. Not a Play policy concern either way — this is a supported Gradle configuration
+      choice. See `CHANGELOG.md`'s `[Unreleased]` entry and `DECISIONS.md`'s "Localization"
+      section.
 - [x] `./gradlew lint` reports zero `MissingTranslation`/`ExtraTranslation`/`StringFormatMatches`/
       `StringFormatCount` findings across all 8 locales in both modules — every translation key
       and format-argument count matches the English source exactly.

docs/play-store/RELEASE_NOTES.md

@@ -12,6 +12,43 @@ heading:
 See [`CHECKLIST.md`](CHECKLIST.md) for the rest of the submission checklist and the
 versionCode/versionName convention this file follows.
 
+## versionCode 6 — versionName 1.0.0 — Closed testing (2026-09-03)
+
+### What's new (paste into Play Console)
+
+```
+Fixed: changing the app's language in Settings > Apps > TapSense > Language now actually takes effect. Previously it silently did nothing for some testers.
+
+No other changes in this build.
+```
+
+(200 characters.)
+
+### What actually changed (internal)
+
+- **Fixed in-app language switching in the release build.** Reported by a closed tester on
+  versionCode 5: picking a different language in Settings → Apps → TapSense → Language had no
+  effect, even though the identical switch worked fine on a sideloaded debug build. Root cause:
+  an Android App Bundle splits resources by language into separate install-time delivery APKs by
+  default, so a device only receives the single locale split matching its language at install
+  time — Play is supposed to fetch additional splits on demand when the per-app language changes,
+  but that delivery proved unreliable, leaving the app stuck on whichever locale it was originally
+  installed with. Confirmed via `aapt2 dump configurations`/`dump xmltree`/`dump resources` that
+  the versionCode 5 release APK's `resources.arsc`, `locales_config.xml`, and every translated
+  string were fully intact — resource shrinking/minification was never the cause, only the App
+  Bundle's language-split delivery was. Fixed with `bundle { language { enableSplit = false } }`
+  in `app/build.gradle.kts` — Android's own documented fix for apps whose language changes
+  independent of the system locale
+  (https://developer.android.com/guide/app-bundle/configure-base) — so every install now packages
+  every locale's resources into the base module instead of depending on Play to deliver the rest
+  later. Verified by decoding the rebuilt `.aab`'s `BundleConfig.pb`
+  (`SplitDimension{value: LANGUAGE, negate: true}`) and re-confirming `assembleRelease`/
+  `bundleRelease` both still succeed. Not a Play Store policy issue in either direction — disabling
+  the split is a supported, policy-neutral Gradle configuration choice; the only trade-off is a
+  small download-size increase (translated strings only) applied to every install rather than
+  just non-English devices. See `CHANGELOG.md`'s `[Unreleased]` section and
+  `DECISIONS.md`'s "Localization" section for full detail.
+
 ## versionCode 5 — versionName 1.0.0 — Closed testing (2026-09-03)
 
 ### What's new (paste into Play Console)