APK Downloader
·15 min read

Sideloaded APK Ignores the System Language: Android 13 Per-App Language and localeConfig, Diagnosed Step by Step

You switched the system language to Chinese, but a sideloaded app still shows English. Or the app simply isn't listed under Settings -> App languages, and switching the system language changes nothing. Reinstalling, clearing data and hunting for a 'localised build' don't help. This is rarely missing translation - since Android 13 (API 33), per-app language preferences decide which language an app uses: the app must declare android:localeConfig to appear in the system list, and actual strings depend on resource qualifiers, AAB language splits and build-time resConfigs shrinking. A full mechanism table, runnable adb / aapt / curl commands, a nine-step diagnostic path, a status reference, version differences, an FAQ, and verified internal links.

per-app languagelocaleConfigresource qualifiersadbtroubleshooting

There is a class of problem that gets filed under "I downloaded the international build without localisation". The system language is set to Chinese, yet a sideloaded app still renders entirely in English. Open Settings -> System -> Languages -> App languages and the app is nowhere in the list. People toggle the system language back and forth, clear data, reinstall, hunt for a "Chinese edition" - and the app does not budge. Stranger still, the very same APK shows Chinese on a friend's phone.

So the cycle repeats: swap builds, install language packs, look for a patched translation. Almost none of that reaches the cause. The fact that it installs, opens and every button works proves the app is intact. Language is wrong because, since Android 13 (API 33), "which language an app uses" is no longer decided solely by the system language. Android introduced per-app language preferences, and three separate things now matter: whether the app declares android:localeConfig (so it appears in the system list), whether the APK actually ships values-xx-rXX resources (so Chinese exists at all), and whether the app overrides or caches the Locale itself (so it listens to the system).

At least four layers sit on that path: the manifest's localeConfig declaration, the language resource directories actually packaged, whether AAB language splits were installed alongside base.apk, and app-side language handling through AppCompatDelegate / LocaleManager. Sideloading hits these especially hard, because files obtained outside an app store are often just a single base.apk - and multi-language resources are exactly what gets split out into separate APKs.

This article takes the chain apart: four distinct failure shapes, a mechanism table identifying the responsible layer, copy-paste adb / aapt / curl commands, a nine-step diagnostic path, a status reference, version differences, an FAQ and verified internal links. Two actions do the heavy lifting: `aapt dump` / `unzip` to confirm whether Chinese resources exist in the file, and `cmd locale` to read and write the app's per-app language preference.

1. Separate the four kinds of "wrong language" before swapping builds

Language problems vary on the surface, but the cause lands in one of four buckets:

  • The app is missing from the language list. Under Settings -> App languages there is no entry for it, so you cannot assign a language. Classic missing android:localeConfig - the system does not know which languages the app supports, so it creates no entry.
  • Switching the system language does nothing. The system is Chinese, the app stays English, even after a reboot. Usually the app caches a Locale or implements its own language switch with a hard-coded default, bypassing the system configuration.
  • Part Chinese, part English. Menus and settings are localised, but some dialogs, error strings or server-delivered copy remain English. Typically hard-coded strings or untranslated server responses - unrelated to the client resource bundle.
  • A "localised build" makes it worse. After installing one you get tofu boxes, broken layout, or a crash on some screens. Common when only base.apk was installed without its language split, or when a resource qualifier mismatch triggers a bad fallback.

Three distractors to rule out immediately: the system language change has not actually taken effect (some ROMs need a reboot or re-login), the app has its own in-app language setting (which outranks the system), and missing glyphs / tofu boxes (a font rendering issue, not missing translation). Section 5 has a check for each.

2. Mechanism table: what each layer decides

The table below lists every rule between "system language" and "words on screen". Match the symptom column against your command output.

Layer / triggerSystem or app behaviourResultTypical symptom
No android:localeConfig in manifestSystem generates no per-app language entryCannot set a language for itApp missing from the list
localeConfig declared and includes zhSystem lists the app and allows selection"Chinese (Simplified)" selectableCorrectly adapted build
targetSdk <= 32, no AppCompat adaptationPer-app language API unavailable; follows systemOnly a global change worksOld APKs need system-wide switching
AppCompatDelegate.setApplicationLocales() usedApp manages and persists its own languageOverrides system preferenceSystem change has no effect
App caches Locale / hard-coded defaultStartup reuses old configurationLanguage fixedChanges briefly after reinstall/clear data
No values-zh-rCN (or similar) in APKNo Chinese string resourcesFalls back to default (usually English)All English regardless of settings
Only values-zh, no region qualifierRegion fallbackChinese, but possibly Traditional wordingSome copy reads oddly
AAB language split not installed with baseLanguage resources absentFalls back to defaultHigh incidence with single-file sideloads
resConfigs / build-time shrinkingUnlisted languages stripped at build timeChinese resources deletedEven a "Chinese build" is English
Hard-coded strings / server copyBypasses the resource systemSome screens unlocalisedMixed Chinese and English
cmd locale set-app-locales set to non-zhPer-app preference overrides systemShows English aloneSystem Chinese, app English
Missing glyphs / unadapted RTLRendering-layer problemTofu boxes or misalignmentNot a translation problem

The most misunderstood point: "the app appears in the system language list" and "the app actually has Chinese" are different things. The first is decided by localeConfig in the manifest; the second by the values-* directories actually present in the APK. An app can declare Chinese support without shipping Chinese strings, or ship Chinese strings while never appearing in Settings because it never declared them. Check both sides - do not judge from the Settings page alone.

3. localeConfig and language splits are the two sideloading traps

What localeConfig is. Since Android 13, an app can declare android:localeConfig="@xml/locales_config" on <application> in AndroidManifest.xml, pointing at a file such as res/xml/locales_config.xml containing entries like <locale android:name="zh-CN"/> and <locale android:name="en"/>. The system reads it to learn which languages the app supports, generates the entry under Settings -> App languages, and accepts writes from LocaleManager.setApplicationLocales() or cmd locale. Without the declaration, the system neither shows an entry nor applies a per-app preference to that app.

The second trap: AAB language splits. To cut download size, modern apps ship as Android App Bundles with language splitting enabled by default (android.bundle.language.enableSplit=true). Chinese, English and other resources go into separate APKs such as split_config.zh.apk and split_config.en.apk, while base.apk holds only the default language. If a third-party channel gives you just base.apk and you install only that, the app consistently falls back to the default language - the single most common explanation for "it was supposed to be the Chinese build but it's still English". pm path reveals it instantly: a healthy install lists base plus several splits; a single base line means missing packages.

The third layer: app-managed language. To support in-app switching even on Android 12 and below, many apps integrate AppCompatDelegate.setApplicationLocales() from AppCompat 1.6.0+ and persist the choice in SharedPreferences. Change the system language and the app writes its own preference back at startup, which looks exactly like "it ignores the system". cmd locale reads and writes that state directly, so no translation pack is needed.

4. Runnable command list

All commands below run from a computer over adb, or directly against a local APK file; none require root. Replace <pkg> with the target package (e.g. com.example.app) and <apk> with a local path.

# 1. Confirm device, package name, and most importantly: are splits installed?
adb devices
adb shell pm list packages | grep -i example
adb shell pm path com.example.app
# A healthy install prints base.apk + split_config.*.apk lines; one base.apk line means missing language splits

# 2. Read targetSdk and the manifest localeConfig declaration
aapt dump badging app.apk | grep -E "package:|targetSdkVersion:|locale"
apkanalyzer manifest application-id app.apk
apkanalyzer manifest target-sdk app.apk
aapt dump xmltree app.apk AndroidManifest.xml | grep -i -A4 -B2 "localeConfig\|locale"

# 3. The most direct step: list which language resource directories are actually packaged
unzip -l app.apk | grep -E "res/values-(zh|en|ja|ko|ru|de|fr|es)|values-zh-rCN|values-zh-rTW"
aapt dump resources app.apk | grep -i -A3 "config zh\|config en" | head -40
# If resources live in splits, run this for each one
for f in split_config.*.apk; do echo "--- $f"; unzip -l "$f" | grep -E "values-zh|values-en"; done

# 4. Read / write the app's per-app language preference (Android 13+)
adb shell cmd locale get-app-locales com.example.app
adb shell cmd locale set-app-locales com.example.app --locales zh-CN
adb shell cmd locale set-app-locales com.example.app --locales ""   # clear = follow system
adb shell cmd locale get-system-locales

# 5. Open the system per-app language page for this app directly
adb shell am start -a android.settings.APP_LOCALE_SETTINGS -d "package:com.example.app"

# 6. Check system language, region and persisted configuration
adb shell getprop persist.sys.locale
adb shell getprop persist.sys.language
adb shell getprop persist.sys.country
adb shell settings get system system_locales
adb shell dumpsys package com.example.app | grep -i -A6 "localeConfig\|locales\|resource"

# 7. Detect app-managed language (cached preference shows up in Configuration / logs)
adb shell dumpsys activity top | grep -i -E "locale|Locales|Configuration"
adb logcat -c && adb logcat -s AppCompatDelegate LocaleManager ResourcesManager AndroidRuntime | grep -i -E "locale|language|config"

# 8. Inspect installed splits and their names
adb shell pm dump com.example.app | grep -i -A20 "splits\|splitNames\|codePath"
adb shell cmd package dump com.example.app | grep -i "split"

# 9. Add language splits over adb (all splits must share base's signature and versionCode)
adb install-multiple base.apk split_config.zh.apk split_config.xxhdpi.apk
adb shell pm install-create -S 0 2>/dev/null || true
# Or commit a session with pm install-commit; every split must match signature and version

# 10. From the PC, check whether a language-pack / server-copy endpoint is reachable
curl -sSI "https://www.example.com/i18n/zh-CN.json" | head -20
curl -sS -o /dev/null -w "http_code=%{http_code} bytes=%{size_download}\n" "https://www.example.com/i18n/zh-CN.json"

Usage notes. pm path in step 1 is the fastest signal for missing language splits - do it first. unzip -l in step 3 only lists names, it does not extract; aapt dump resources goes further into specific configs. cmd locale in step 4 is an Android 13+ shell command; if the device reports "not found", it is an older system and you should use the Settings action in step 5. install-multiple in step 9 requires every split to share the base's signature and versionCode, otherwise you get INSTALL_FAILED_INVALID_APK or a signature mismatch - which is exactly why randomly combining language packs from different sources is a bad idea. The curl in step 10 confirms whether mixed-language copy is coming from an unlocalised server response; if the endpoint only returns English, no client-side language switch will change it.

5. Nine-step diagnostic path

Work in order and stop as soon as one step identifies the cause.

  1. Classify the symptom using the four buckets: missing from Settings, system change ignored, partially mixed, or worse after a build swap. If it is only tofu boxes or RTL misalignment, that is the rendering layer, outside this chain.
  2. Read `pm path`: a single base.apk line -> language splits missing, jump to step 8; multiple lines including zh -> continue.
  3. List the APK's language resource directories with unzip -l / aapt dump resources to confirm values-zh-rCN or similar exists. None at all -> this build has no Chinese; switch to a complete build or accept English and stop.
  4. Read the `localeConfig` declaration with aapt dump xmltree / apkanalyzer manifest print on <application>, and check whether it includes zh. Missing -> no Settings entry, but that alone does not mean Chinese resources are absent.
  5. Read the per-app language preference with cmd locale get-app-locales <pkg>. If it returns a non-Chinese locale, it was explicitly set; clear it with set-app-locales --locales "" to follow the system.
  6. Verify the system language really took effect: getprop persist.sys.locale, settings get system system_locales, and if needed reboot once; some ROMs only reload resources after the configuration broadcast completes.
  7. Check for app-managed language: the Configuration in dumpsys activity top and AppCompatDelegate keywords in logcat. If the app rewrites the preference at startup, change it in the app's own Settings -> Language rather than the system.
  8. Add the language splits: if you have splits with matching signature and version, use adb install-multiple; otherwise reinstall from a channel that provides the complete APK set. Mixing splits from different sources fails on signature mismatch.
  9. Separate client-side from server-side copy: use the curl check in step 10. If the i18n endpoint only returns English, the mixed language is server-side non-localisation and nothing on the client can fix it - report it upstream.

6. Status and error reference

Symptom / command outputLayerMeaningNext step
App absent from App languages listManifest declarationMissing android:localeConfigStep 4
localeConfig has zh, UI still EnglishPreference / cacheSet to non-Chinese or app-managedSteps 5, 7
get-app-locales returns en / emptyPer-app preferenceOverriding or following systemset-app-locales or clear
pm path shows only base.apkMissing splitsLanguage splits not installedStep 8
unzip -l shows no values-zh*Missing resourcesBuild has no ChineseGet a complete build
Only values-zh, no zh-rCNQualifierRegion fallback, possible Traditional mixGet matching region build
INSTALL_FAILED_INVALID_APKAdding splitsSignature / version mismatchVerify source consistency
cmd locale: not foundOS versionDevice below Android 13Use the Settings page
Some screens mixed languageHard-coded / serverBypasses resource systemStep 9 curl
Tofu boxes / missing glyphsFont renderingNot a translation problemChange font or OS version
Needs reboot after system changeROM behaviourDelayed configuration broadcastReboot once, then re-check

7. Version differences

Android versionKey changePractical effect on sideloaded builds
Android 12 (API 32) and belowNo system-level per-app language; apps can self-manage via AppCompatOnly system-wide change or in-app setting
Android 13 (API 33)Per-app language preferences, localeConfig, LocaleManager, cmd locale introducedThe watershed where the app entry appears or is missing
Android 14 (API 34)More standard locale fallback and regional preferences (temperature unit, first day of week)Region qualifiers matter more
Android 15 / 16Same preference model; finer partial localisation and system language settingsPartially localised apps mix languages more easily

8. FAQ

Q1: Will installing a "Chinese / localised build" fix it?

Depends on the cause. If the original build ships no values-zh* resources at all, a localised or official complete build is genuinely needed. But if the issue is a missing localeConfig, a preference set to English, or missing language splits, swapping builds treats the symptom - and patched translations from unknown sources carry repackaging and signing risk.

Q2: Why isn't this app listed under App languages?

Because it does not declare android:localeConfig in the manifest. The system relies on that declaration to know which languages the app supports and to generate the entry; without it, Chinese resources inside the APK still will not produce a Settings entry.

Q3: Does clearing data or reinstalling help?

Clearing data can help when the app self-manages language and persists its choice - it wipes the stored selection. It does nothing for a missing localeConfig, missing resources or missing language splits. Check cmd locale get-app-locales first to decide.

Q4: What does `cmd locale set-app-locales` do?

It is the Android 13+ shell interface for reading and writing one app's per-app language preference. Setting zh-CN takes effect immediately (possibly after an app restart); an empty string clears the preference so the app follows the system language. It is far faster than hunting through Settings.

Q5: What are language splits, and why does sideloading lose them?

AAB splits resources by language by default: Chinese lives in split_config.zh.apk, base.apk holds only the default language. If a third-party channel supplies just base.apk, the app consistently falls back to English. A single line from pm path is the clear signal.

Q6: Can I add the language splits myself?

Yes, with adb install-multiple base.apk split_config.zh.apk ..., but every split must share base's signature and versionCode; mixing sources fails and can break the install. Reinstalling from a channel that provides the full APK set is safer.

Q7: Some screens are Chinese and some English - is the translation incomplete?

Not necessarily a resource problem. Strings hard-coded in code and copy delivered from a server bypass the resource system and never change with language. The curl check in step 10 confirms whether it comes from the server.

Q8: Do I need to reboot after changing the system language?

Usually not, but some ROMs only reload resources once the configuration broadcast completes, and individual apps may cache the Locale until their process restarts. If persist.sys.locale is already correct but the old language persists, reboot once before concluding anything.

Q9: Which wins, the app's own language setting or the system setting?

The in-app setting usually wins, because the app actively rewrites its preference at startup via AppCompatDelegate or its own persistence. When a system change has no effect, look for a language option inside the app, or read the effective preference with cmd locale.

Q10: When should I conclude "this build simply has no Chinese" and stop?

When pm path shows splits are complete, unzip -l still finds no values-zh* directory, and aapt dump resources shows no Chinese config. The conclusion is settled: switch to an official complete build with Chinese resources, or accept English - stop toggling the system language.

9. Further reading

These in-site articles sit adjacent to this diagnostic chain:

Bottom line

"Sideloaded APK ignores the system language" is more than a missing translation - it is the combined result of Android 13 per-app language preferences, localeConfig declarations, resource qualifiers and AAB language splits. Two actions do the heavy lifting: `pm path` / `unzip -l` to confirm whether Chinese resources exist and whether language splits were installed, and `cmd locale get-app-locales` / `set-app-locales` to read and write the preference actually in effect. The first answers "is there Chinese at all"; the second answers "why isn't it being used". If splits are missing, add splits with matching signature and version or get a complete build; if the build has no Chinese resources, stop toggling the system language.