侧载 APK 语言不跟随系统:Android 13 每应用语言与 localeConfig 逐层排查
有一类问题特别容易被归结为「下到了没汉化的国际版」:系统语言明明已经切成简体中文,装好的第三方 APK 界面却还是全英文;打开「设置 → 系统 → 语言和输入法 → 应用语言」,列表里翻半天找不到这个应用;有人把系统语言来回切、清数据、重装、甚至去找「中文版」,应用纹丝不动。更怪的是,同一个 APK 在朋友的手机上显示中文,在自己手机上就是英文。
于是很多人反复换包、装语言包、找汉化版。但这些动作大多碰不到根因。能装上、能打开、按钮都能点,说明应用本身是完整的;语言不对,是因为从 Android 13(API 33)开始,「应用用哪种语言」不再只由系统语言单向决定——系统引入了每应用语言偏好(per-app language preferences),应用是否出现在系统语言列表、是否响应偏好、以及它到底带了多少语言资源,是三件彼此独立的事。
这条链路上至少有四层:应用清单里有没有声明 android:localeConfig(决定系统设置里能不能单独给它选语言)、APK 里实际打包了哪些 values-xx-rXX 资源目录(决定有没有中文可显示)、如果是 AAB 拆分的语言分包是否一起装上(决定语言资源是否缺失)、以及应用自己是否用 AppCompatDelegate / LocaleManager 覆盖或缓存了语言(决定它听不听系统的话)。侧载场景尤其容易踩坑,因为从应用商店以外拿到的往往只有一个 base.apk,而多语言资源恰恰常被拆在独立的 split 里。
本文把这条链路拆开:先分清四种「语言不对」,用机制表格定位是哪一层,再给出可直接复制执行的 adb / aapt / curl 命令、九步排查路径、状态速查、版本差异,最后是常见问题与站内延伸阅读。核心动作只有两个:用 `aapt dump` / `unzip` 确认 APK 里到底有没有中文资源,以及用 `cmd locale` 读写这个应用的每应用语言设置。
一、先分清四种「语言不对」,别一上来就换包
语言问题的表现差异很大,但根因层不出这四类:
- 第一类:应用设置里找不到它。进「设置 → 应用语言」,列表里压根没有这个应用,无法单独指定语言。这是
android:localeConfig未声明的典型表现——系统不知道该应用支持哪些语言,就不给它条目。 - 第二类:切了系统语言,应用不动。系统语言切到中文,应用仍显示英文,重启也一样。多半是应用内部缓存了 Locale、或自己实现了语言切换并写死了默认值,绕过了系统配置。
- 第三类:应用部分中文部分英文。菜单、设置页是中文,某些弹窗、错误提示、服务端下发的文案仍是英文。这类通常是硬编码字符串或服务端返回未本地化的文案,与客户端资源包无关。
- 第四类:换了「中文版」反而更糟。装上后出现缺字、方框、布局错乱,或某些页面直接崩。常见于只装了
base.apk却缺语言 split,或资源限定符与系统 locale 不匹配触发了错误回退。
需要立刻排除的干扰项:系统语言本身没真正生效(部分 ROM 需要重启或重新登录)、应用有独立的内置语言设置(在应用自己的「设置 → 语言」里,优先级高于系统)、以及字体缺失导致的方框(那是字体渲染问题,不是翻译缺失)。第五节的排查路径对这三类都有对应检查。
二、机制表格:四层分别在决定什么
下表把从「系统语言」到「屏幕上的字」之间会遇到的规则逐条列出。「现象」一列可直接对照命令输出。
| 层 / 触发条件 | 系统或应用行为 | 结果 | 典型现象 |
|---|---|---|---|
清单未声明 android:localeConfig | 系统不生成该应用的应用语言条目 | 无法单独指定语言 | 设置里找不到这个应用 |
声明了 localeConfig 且含 zh | 系统列出该应用并允许选择 | 可设「简体中文」 | 正确的适配姿势 |
| targetSdk ≤ 32,无 AppCompat 适配 | 每应用语言 API 不可用,跟随系统语言 | 切系统语言才生效 | 老 APK 只能全局切换 |
应用用 AppCompatDelegate.setApplicationLocales() | 应用自管语言并持久化 | 覆盖系统偏好 | 切系统语言无效 |
| 应用缓存了 Locale / 写死默认 | 启动时用旧配置 | 界面语言固定 | 重装、清数据后才短暂变化 |
APK 无 values-zh-rCN 等目录 | 无中文字符串资源 | 回退到默认(通常英文) | 全英文,怎么切都没用 |
只有 values-zh(无地区限定) | 简繁/地区回退 | 显示中文但用词可能偏繁体 | 部分文案别扭 |
| AAB 语言分包未随 base 一起安装 | 语言 split 缺失 | 回退默认语言 | 侧载单 base.apk 高发 |
resConfigs / 构建裁剪 | 打包时剔除未列语言 | 中文资源被删 | 「中文版」也全英文 |
| 硬编码字符串 / 服务端文案 | 不走资源系统 | 部分界面不本地化 | 中英混杂 |
cmd locale set-app-locales 设为非 zh | 每应用偏好覆盖系统 | 单独显示英文 | 系统中文但应用英文 |
| 字体缺字 / RTL 布局未适配 | 渲染层问题 | 方框或错位 | 非翻译问题 |
最容易被误解的一点:「应用出现在系统语言列表里」和「应用真的有中文」是两回事。前者由清单里的 localeConfig 决定,后者由 APK 里实际存在的 values-* 资源目录决定。一个应用可以声明支持中文却没打包中文资源,也可以打包了中文却因为没声明而不出现在设置里。所以排查必须两边都查,不能只看设置页。
三、localeConfig 与 split 是侧载的两个高频坑
localeConfig 是什么:Android 13 起,应用可在 AndroidManifest.xml 的 <application> 上声明 android:localeConfig="@xml/locales_config",指向一个形如 res/xml/locales_config.xml 的文件,内容是一组 <locale android:name="zh-CN"/>、<locale android:name="en"/> 这样的条目。系统读取它,才知道「这个应用支持哪些语言」,从而在「设置 → 应用语言」里生成条目,并接受 LocaleManager.setApplicationLocales() 或 cmd locale 的写入。没有这个声明,系统既不给条目,也不会把每应用偏好应用到它身上。
第二个坑是 AAB 语言分包。为了减小体积,现代应用常用 Android App Bundle 发布,Gradle 默认开启按语言拆分(android.bundle.language.enableSplit=true),中文、英文等语言资源被打进 split_config.zh.apk、split_config.en.apk 这类独立 APK,而 base.apk 里只有默认语言。从第三方渠道侧载时,如果只拿到并安装了 base.apk,语言 split 没跟上,应用就会稳定回退到默认语言——这正是「明明是中文版,装完还是英文」的最常见解释。用 pm path 一看便知:健康安装会列出 base 加若干 split,只有一行 base 就是缺包。
第三层是应用自管语言。不少应用为了在 Android 12 及以下也支持应用内切换,接入了 AppCompat 1.6.0+ 的 AppCompatDelegate.setApplicationLocales(),并把选择持久化在 SharedPreferences 里。此时系统语言改了,应用启动时又把自己的偏好写回去,看起来就是「不听系统的话」。这类问题用 cmd locale 能直接读写,不必求助于汉化包。
四、可直接执行的命令清单
以下命令在电脑侧通过 adb 执行,或直接对本地 APK 文件执行,不需要 root。把 <pkg> 换成目标应用包名(如 com.example.app),<apk> 换成本地文件路径。
# 1. 确认设备、包名,以及最关键的一项:是否装了 split
adb devices
adb shell pm list packages | grep -i example
adb shell pm path com.example.app
# 健康安装会输出多行 base.apk + split_config.*.apk;只有一行 base.apk 即语言分包缺失
# 2. 读 targetSdk 与清单里的 localeConfig 声明
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. 最直观的一步:列出 APK 里实际打包了哪些语言资源目录
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
# 若资源在 split 里,对每个 split 都跑一遍
for f in split_config.*.apk; do echo "--- $f"; unzip -l "$f" | grep -E "values-zh|values-en"; done
# 4. 读取/设置该应用的每应用语言偏好(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 "" # 清空=跟随系统
adb shell cmd locale get-system-locales
# 5. 直接打开系统为该应用准备的应用语言设置页
adb shell am start -a android.settings.APP_LOCALE_SETTINGS -d "package:com.example.app"
# 6. 查系统语言、地区与持久化配置
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. 查应用是否自管语言(自管偏好常写在 SharedPreferences / 配置里)
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. 检查 split 安装状态与已安装分包列表
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. 用 adb 补装语言分包(若手上有对应 split 文件,签名须与 base 一致)
adb install-multiple base.apk split_config.zh.apk split_config.xxhdpi.apk
adb shell pm install-create -S 0 2>/dev/null || true
# 也可用 pm install-commit 走 session;注意同一应用所有 split 必须同签名、同版本号
# 10. 从电脑侧核对「语言包 / 服务端文案」接口是否可达
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"几点使用说明。第 1 步 pm path 是判断语言分包缺失最快的信号,务必先做。第 3 步 unzip -l 只列文件名,不会解压;aapt dump resources 能进一步看具体 config。第 4 步 cmd locale 是 Android 13+ 的 shell 命令,若提示命令不存在说明设备系统较旧,改走第 5 步的设置页。第 9 步 install-multiple 要求所有 split 与 base 同签名、同 versionCode,否则会报 INSTALL_FAILED_INVALID_APK 或签名不一致;这也是不建议随便混拼不同来源语言包的原因。第 10 步的 curl 用于确认「中英混杂」是否来自服务端下发的未本地化文案——若接口只返回英文,客户端再怎么切语言也不会变。
五、九步排查路径
按顺序做,任何一步定位到根因即可停止。
- 分清属于四类里的哪一类:设置里找不到、切系统无效、部分中英混杂、还是换包后更糟。若只是字体方框或 RTL 错位,属渲染层,不在这条链路。
- 看 `pm path` 输出:只有一行
base.apk→ 语言 split 缺失,跳第 8 步;有多行 split 且含zh→ 继续。 - 列 APK 语言资源目录:
unzip -l/aapt dump resources确认有没有values-zh-rCN一类目录。完全没有 → 这个构建本身不带中文,换包或接受英文,其余步骤可省。 - 读 `localeConfig` 声明:
aapt dump xmltree/apkanalyzer manifest print看<application>上有没有android:localeConfig及其中是否含zh。未声明 → 系统设置里不会有条目,但不代表没中文资源。 - 读每应用语言偏好:
cmd locale get-app-locales <pkg>。若返回一串非中文 locale,说明被单独设过,用set-app-locales --locales ""清空让它跟随系统。 - 核对系统语言真的生效:
getprop persist.sys.locale、settings get system system_locales,必要时重启一次;部分 ROM 改语言后要等配置广播走完才生效。 - 检查应用自管语言:
dumpsys activity top的 Configuration 与 logcat 里的AppCompatDelegate关键字;若发现应用启动即回写偏好,去应用自身的「设置 → 语言」里改,而不是改系统。 - 补装语言分包:手上有同签名同版本的 split 时用
adb install-multiple补上,或改从提供完整 APK 集的渠道重装;注意混拼不同来源的分包会因签名不一致失败。 - 区分客户端与服务端文案:用第 10 步
curl核对 i18n 接口;若服务端只返回英文,中英混杂属于服务端未本地化,客户端无解,反馈开发者即可。
六、状态与错误速查表
| 现象 / 命令输出 | 归属层 | 含义 | 下一步 |
|---|---|---|---|
| 应用语言设置里找不到该应用 | 清单声明 | 缺 android:localeConfig | 第 4 步 |
localeConfig 有 zh 但界面仍英文 | 偏好 / 缓存 | 偏好被设为非中文或应用自管 | 第 5、7 步 |
get-app-locales 返回 en / 空 | 每应用偏好 | 覆盖或跟随系统 | set-app-locales 或清空 |
pm path 只有 base.apk | 分包缺失 | 语言 split 未安装 | 第 8 步 |
unzip -l 无 values-zh* | 资源缺失 | 该构建不带中文 | 换完整包 |
只有 values-zh 无 zh-rCN | 限定符 | 地区回退,简繁可能混 | 换对应地区包 |
INSTALL_FAILED_INVALID_APK | 补装 split | 签名/版本不一致 | 核对来源一致性 |
cmd locale: not found | 系统版本 | 设备低于 Android 13 | 走设置页 |
| 部分界面中英混杂 | 硬编码 / 服务端 | 不走资源系统 | 第 9 步 curl |
| 方框 / 缺字 | 字体渲染 | 非翻译问题 | 换字体或系统版本 |
| 切系统语言后需重启才生效 | ROM 行为 | 配置广播延迟 | 重启一次再判断 |
七、版本差异速查
| Android 版本 | 关键变化 | 对侧载包的现实影响 |
|---|---|---|
| Android 12(API 32)及以下 | 无系统级每应用语言;应用可用 AppCompat 自管 | 只能靠切系统语言或应用内设置 |
| Android 13(API 33) | 引入每应用语言偏好、localeConfig、LocaleManager、cmd locale | 应用语言条目出现/缺失的分水岭 |
| Android 14(API 34) | 更规范的 locale 回退与区域偏好(如温度单位、星期首日) | 地区限定符影响更明显 |
| Android 15/16 | 延续偏好模型,partial localization 与系统级语言设置更细 | 部分本地化应用更易中英混杂 |
八、常见问题 FAQ
Q1:装「中文版 / 汉化版」能解决吗?
取决于根因。若原构建压根没打包 values-zh* 资源,汉化版(或官方完整包)确实必要;但如果只是 localeConfig 未声明、每应用偏好被设成英文、或缺语言 split,换包治标不治本,且来路不明的汉化包有重打包与签名风险。
Q2:为什么系统设置里找不到这个应用的语言选项?
因为它没在清单里声明 android:localeConfig。系统靠这个声明才知道应用支持哪些语言并生成条目;缺声明时,即使 APK 里有中文资源也不会出现在列表里。
Q3:清数据 / 重装有用吗?
清数据对「应用自管语言并持久化偏好」有效——它会把写死的选择清掉;对 localeConfig 缺失、资源缺失、语言 split 缺失一律无效。先用 cmd locale get-app-locales 判断再决定。
Q4:`cmd locale set-app-locales` 是做什么的?
它是 Android 13+ 提供的 shell 接口,可直接读写某个应用的每应用语言偏好。设为 zh-CN 立刻生效(可能需重启应用),设为空串表示清除偏好、跟随系统语言。比在设置里翻找快得多。
Q5:什么是语言 split,为什么侧载容易缺?
AAB 默认按语言拆分资源,中文在 split_config.zh.apk 里,base.apk 只有默认语言。第三方渠道若只提供 base.apk,装完就会稳定回退英文。pm path 只有一行是明确信号。
Q6:能自己补装语言 split 吗?
可以,用 adb install-multiple base.apk split_config.zh.apk ...,但所有分包必须与 base 同签名、同 versionCode,混拼不同来源必然失败且可能破坏安装。更稳妥的做法是从提供完整 APK 集的渠道重装。
Q7:部分界面是中文、部分是英文,是没汉化完吗?
不一定是资源问题。硬编码在代码里的字符串和服务端下发的文案都不走资源系统,切语言不会变。用第 10 步的 curl 核对 i18n 接口即可确认是否来自服务端。
Q8:切了系统语言要重启吗?
多数情况不需要,但部分 ROM 只在配置广播完成后重新加载资源,个别应用还会缓存 Locale 直到进程重启。若 persist.sys.locale 已正确却仍显示旧语言,重启一次再判断。
Q9:应用自己有语言设置,和系统设置谁优先?
应用内设置通常优先,因为它通过 AppCompatDelegate 或自己的持久化偏好在启动时主动回写。遇到「切系统无效」,先去应用自身的设置里找语言项,或用 cmd locale 读它实际生效的偏好。
Q10:什么时候该判定为「这个构建就是没有中文」,停止排查?
当 pm path 显示分包齐全、unzip -l 仍找不到任何 values-zh* 目录、aapt dump resources 也没有中文 config 时,结论已经确定:换用带中文资源的官方完整构建,或接受英文界面,不必再折腾语言偏好。
九、延伸阅读
下面这些站内文章与本文的排查链路相邻,可按需跳转:
- APK 文件结构解析:res/values-* 与 resources.arsc 的关系
- APK 体积为什么越来越大:分包、密度拆分与裁剪
- APK 版本类型选择指南:universal、密度包与地区包
- APK 与 AAB 的区别:为什么语言资源会被拆出去
- XAPK / APKS / APKM 安装指南:如何把 split 一起装全
- 装完 APK 检测不到、拉不起别的应用:同属清单声明决定系统行为
- 侧载 APK 设为默认应用不生效:另一类「设置里找不到」的机制
- 装完 APK 内嵌网页白屏:服务端文案与本地资源的区别
- targetSdkVersion 说明:为什么它决定能用到哪些新 API
- Android 14/15 侧载变化:新系统对配置与资源的调整
- APK 安装错误码速查:补装 split 失败时对照
- APK 下载安装核对清单:从下载到验证的完整流程
小结
「侧载 APK 语言不跟随系统」不是没汉化那么简单,而是 Android 13 之后每应用语言偏好、localeConfig 声明、资源限定符与 AAB 语言分包共同作用的结果。排查的关键动作只有两个:用 `pm path` / `unzip -l` 确认 APK 里到底有没有中文资源、语言 split 是否装全,以及用 `cmd locale get-app-locales` / `set-app-locales` 读写这个应用实际生效的语言偏好。前者回答「有没有中文」,后者回答「为什么没用中文」。确认是分包缺失,就补装同签名同版本的 split 或换完整包;确认是构建本身不带中文,就别再反复切换系统语言了。