Java ResourceBundle.Control 怎样控制语言回退链

如果系统支持中文、法语和加拿大法语，资源缺失时最容易出现的问题不是“找不到文件”，而是悄悄回退到了另一套语言。Java 的 ResourceBundle.Control 可以把这条规则拆开控制：getCandidateLocales 决定候选 Locale 和资源包父链，getFallbackLocale 决定候选链找不到后是否继续尝试默认 Locale。

想让回退规则可控，就先固定候选 Locale 链，再明确额外回退策略；如果不允许跨到默认语言，直接使用 getNoFallbackControl 或让 getFallbackLocale 返回 null。

官方文档：https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/ResourceBundle.Control.html

本文用一个小型 Java 资源包项目串起配置、代码和验收。示例只讨论未命名模块或 class path 场景；命名模块中带 Control 参数的工厂调用不适用，应改看 ResourceBundleProvider。

准备资源包与加载目标

先把资源组织成同一个 base name。下面的项目使用 Messages，让加拿大法语优先命中地区资源，再回退到法语，最后回到 root 资源。

Messages_fr_CA.properties：

# 加拿大法语：只放本地区与基础法语不同的文案
welcome=Bienvenue au Canada

Messages_fr.properties：

# 法语：作为 fr-CA 缺失键的父级资源
welcome=Bienvenue

Messages.properties：

# root：所有语言都能接受的最终兜底
welcome=Welcome

调用方的目标 Locale 可以写成 Locale.forLanguageTag("fr-CA")。

自定义候选 Locale 链

默认实现已经会按 Locale 的语言、地区、变体逐级生成候选项，但项目通常还需要一个稳定的约定：候选链必须以 Locale.ROOT 结束，不能把“默认语言”混进本地资源包父链。可以只覆盖 getCandidateLocales，并把不需要的变体去掉。

import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle;

public final class ProjectControl extends ResourceBundle.Control {
    @Override
    public List getCandidateLocales(String baseName, Locale locale) {
        if (baseName == null || locale == null) {
            // 让调用方尽早发现无效参数，不把错误拖到资源加载阶段。
            throw new NullPointerException("baseName and locale are required");
        }
        if (Locale.ROOT.equals(locale)) {
            // root 只对应基础资源，避免再次拼接候选项。
            return List.of(Locale.ROOT);
        }
        if ("fr".equals(locale.getLanguage())) {
            // 项目只接受 fr-CA -> fr -> root 这条本地回退链。
            return List.of(locale, Locale.FRENCH, Locale.ROOT);
        }
        // 其他语言仍回到 root，但不自动跨到系统默认语言。
        return List.of(locale, Locale.ROOT);
    }
}

这里的返回值是候选 Locale 列表，不是“已经找到的文件列表”。当相应资源存在时，列表顺序也会体现在资源包父级关系上。列表返回后不要再修改它；同一个 base name 的 getFormats 与候选 Locale 规则也要保持稳定，否则缓存可能复用到不期望的资源包。

控制额外默认 Locale 回退

候选链和额外回退是两层规则。假设 Messages_fr_CA、Messages_fr 都不存在，候选链可以走到 Messages.properties；如果连结果都没有，getFallbackLocale 才决定是否再用 JVM 默认 Locale 开始一轮新的搜索。

import java.util.Locale;
import java.util.ResourceBundle;

public final class NoCrossLanguageControl extends ResourceBundle.Control {
    @Override
    public Locale getFallbackLocale(String baseName, Locale locale) {
        // 返回 null 表示候选链失败后停止，不跨到 JVM 默认语言。
        return null;
    }
}

如果只想关闭额外回退而不需要自定义候选链，标准库已经提供了更直接的工厂：

ResourceBundle.Control control =
        ResourceBundle.Control.getNoFallbackControl(
                ResourceBundle.Control.FORMAT_PROPERTIES); // 只读 properties，且不做额外 Locale 回退

接入 getBundle 并验收

把自定义 Control 传给带四个参数的 getBundle。为了让示例与前面的资源文件一致，固定使用 properties 格式，避免 class 资源和 properties 资源同时存在时产生优先级误判。

import java.util.Locale;
import java.util.ResourceBundle;

public class Demo {
    public static void main(String[] args) {
        Locale requested = Locale.forLanguageTag("fr-CA");
        ResourceBundle.Control control = new ProjectControl();
        ResourceBundle bundle = ResourceBundle.getBundle(
                "Messages", requested, control); // 按项目规则读取资源包

        // getString 读取当前包或父级包中的键，缺失时抛出 MissingResourceException。
        System.out.println(bundle.getString("welcome"));
    }
}

验收时只看三件事：

• 请求 fr-CA 时，存在地区资源就命中 Messages_fr_CA；缺少该文件或键时，父级关系仍应落到 Messages_fr 和 root。
• 自定义 getFallbackLocale 返回 null 后，不应再因为 JVM 默认语言是中文或英文而跨语言搜索。
• 如果资源包放进命名模块，不要把这个示例的 Control 直接照搬；Oracle 文档说明此场景应使用 ResourceBundleProvider。

常见误区是把 getCandidateLocales 和 getFallbackLocale 当成同一个回退入口：前者描述当前目标 Locale 的候选链，后者处理候选链没有结果时的后续 Locale。先分清这两层，语言回退就不会靠系统默认值“碰运气”。

小结与常见问题

这个小项目的核心不是重写整个资源加载器，而是把规则收敛到两个方法：用 getCandidateLocales 固定本地父链，用 getFallbackLocale 决定是否允许额外跨语言回退；只读 properties 且不需要自定义候选链时，优先使用 getNoFallbackControl。

为什么候选链最后通常要放 Locale.ROOT？

root 对应不带 Locale 后缀的基础资源包。把它放在最后，才能把通用文案作为稳定终点；如果项目明确不提供 root 资源，就要在自己的资源约定中说明缺失行为。

ResourceBundle.Control 能用于命名模块吗？

不能直接按本文方式使用。Oracle 文档把 ResourceBundle.Control 定位为未命名模块场景，命名模块应改用 ResourceBundleProvider 或模块支持的资源查找方式。