Java Locale.Builder 怎么校验用户语言标签：B型格式、回退策略与展示结果

用户在个人设置里提交的语言标签，常见形式是 zh-CN、en-US 或 sr-Latn。如果服务端只用字符串切分再拼接 Locale，遇到大小写、扩展段或非法子标签时，很容易把“格式不合法”和“系统没有这门语言”混成一个问题。Java 的 Locale.Builder 可以在构造阶段按 BCP 47 规则拒绝坏输入，再由业务代码决定回退到默认语言还是保留用户原值。

先把语言标签的两个问题分开

zh-CN 是一个符合 BCP 47 语法的标签，但它是否有完整翻译资源，是另一层业务问题。前者由 Locale.Builder 检查语言、脚本、地区和扩展段的格式；后者需要查应用自己的资源包，例如 messages_zh_CN.properties 是否存在。

这一区分很重要。输入 zh_CN 时，用户可能只是把旧式下划线格式贴了进来；输入 zh-12345 时，则可能是子标签长度错误。两种情况都不应该直接落成一个“语言不支持”的提示。

旧写法为什么会把错误拖到后面

很多早期业务代码处理用户语言标签时，会直接用连字符切割字符串，再调用旧版的Locale构造器生成实例：

String[] parts = rawTag.split("-");
Locale locale = new Locale(parts[0], parts.length > 1 ? parts[1] : "");

这段代码只认识语言和地区两个位置，脚本段、Unicode 扩展和私有扩展都可能被丢掉。更麻烦的是，构造完成并不等于输入符合 BCP 47；后面调用 toLanguageTag() 时才可能出现被替换、被省略或变成私有使用段的结果。

Java 25 的 API 文档仍建议使用 Locale.Builder 或 forLanguageTag，不要把不符合标准的旧式 Locale 构造当成输入校验器。

用 Builder 建立严格的输入边界

拿到用户提交的外部语言标签时，直接用Locale.Builder做语法合法性校验，处理完直接输出统一格式的规范化标签即可：

import java.util.Locale;
import java.util.Locale.Builder;

static Locale parseStrict(String rawTag) {
    if (rawTag == null || rawTag.isBlank()) {
        throw new IllegalArgumentException("language tag is blank");
    }
    return new Builder().setLanguageTag(rawTag).build();
}

Locale locale = parseStrict("zh-Hans-CN");
System.out.println(locale.toLanguageTag()); // zh-Hans-CN

setLanguageTag 会把 Builder 重置为传入的语言标签；如果标签不是格式良好的 BCP 47 字符串，会抛出 IllformedLocaleException。这里不要只捕获所有异常后返回默认语言，否则调用方无法区分空输入、非法格式和资源缺失。

forLanguageTag 适合做宽松解析还是校验

Locale.forLanguageTag 的行为更宽松：如果标签中出现非法子标签，它会忽略第一个非法子标签以及后续内容。例如输入中混入了错误扩展段时，返回的 Locale 可能只保留前半段。这个行为适合兼容历史配置或读取浏览器偏好值，但不能单独证明整条原始字符串合法。

如果业务规则要求用户的传入值不能随便修改，那就开启Builder的严格解析模式，解析完成后对比规范化后的标签内容判断是否合规：

static boolean isWellFormedTag(String rawTag) {
    try {
        Locale locale = new Locale.Builder().setLanguageTag(rawTag).build();
        return locale.toLanguageTag().equals(rawTag);
    } catch (java.util.IllformedLocaleException ex) {
        return false;
    }
}

比较原文和规范化结果时要先明确产品契约。大小写规范化是正常结果，不能简单把 zh-cn 因为输出成 zh-CN 就判为错误；如果要接受这种输入，应记录规范化后的值作为后续缓存和资源查找的键。

回退链要能说明“为什么换语言”

就算标签格式校验通过，还要确认项目里有没有对应的翻译资源。日常开发里常用的回退逻辑一般是先匹配完整的语言+地区标签，去掉地区后单独匹配语言，最后落到项目预设的默认Locale：

static Locale chooseLocale(String rawTag, Locale defaultLocale) {
    try {
        Locale requested = new Locale.Builder().setLanguageTag(rawTag).build();
        if (hasBundle(requested)) {
            return requested;
        }
        Locale languageOnly = Locale.of(requested.getLanguage());
        return hasBundle(languageOnly) ? languageOnly : defaultLocale;
    } catch (java.util.IllformedLocaleException ex) {
        return defaultLocale;
    }
}

static boolean hasBundle(Locale locale) {
    return java.util.ResourceBundle.getBundle("messages", locale)
        .getLocale().getLanguage().equals(locale.getLanguage());
}

这里的 hasBundle 只是示意检查，生产代码还应避免把默认资源包被误认为命中，并把回退原因写入日志字段，例如 invalid-format、region-missing 或 default-locale。

展示文字和持久化标签不要混用

toLanguageTag() 用来保存稳定的机器可读标签，getDisplayName(displayLocale) 更适合生成用户看到的名称：

Locale selected = new Locale.Builder()
        .setLanguageTag("zh-Hans-CN")
        .build();

String stored = selected.toLanguageTag();
String label = selected.getDisplayName(Locale.SIMPLIFIED_CHINESE);
System.out.println(stored); // zh-Hans-CN
System.out.println(label);  // 中文（简体，中国）

界面上展示的语言名称要和当前系统的显示语言保持一致，不要直接把中文的语言名存到数据库的用户语言标签字段里。库里面只存符合规范的标准化标签，前端展示的时候再根据当前界面的Locale生成对应的本地化名称，后续切换界面语言的时候，显示的语言名也能同步更新。

测试时至少覆盖四组边界

1. 正常标签：zh-CN、en-US、sr-Latn 能构造成功，并输出稳定的 toLanguageTag()。
2. 大小写变化：zh-cn 能按产品契约规范化成 zh-CN，不能因为规范化就丢失地区。
3. 非法输入场景：空字符串、单字符语言段、长度不符合规则的地区段、非法扩展参数都要走单独的明确回退分支，不能直接抛错也不能静默忽略。
4. 资源缺失场景：语言标签格式完全正确，但项目里没有准备对应翻译资源的情况，要自动回退到纯语言级的Locale或者全局默认Locale，同时留下后续可检索的回退原因记录。

测试断言不要只比较 Locale 对象。还应断言规范化字符串、资源包实际命中结果和回退原因，否则“对象创建成功但页面仍显示默认语言”的问题很难被发现。

常见问题

Locale.Builder 能判断某种语言是否被应用支持吗？

不能。Locale.Builder本身只负责校验BCP 47语言标签的格式，生成合规的Locale实例；至于当前系统有没有对应的翻译资源、产品侧是否允许该地区访问等业务规则，需要项目自己的资源包配置和产品权限逻辑来判断。

forLanguageTag 和 setLanguageTag 应该怎么选？

需要严格拒绝坏输入时选 Builder 的 setLanguageTag；读取历史配置、允许忽略尾部非法内容时可以用 forLanguageTag，但要把它当作宽松解析而不是完整校验。

为什么保存时推荐 toLanguageTag？

它输出的结果完全符合BCP 47标准，语言、脚本、地区和扩展段的定义比旧版用下划线拼接的Locale更清晰规范，非常适合用来存数据库字段、做缓存键、或者作为接口的跨服务传输参数。

用户输入 zh-cn 要不要直接报错？

不一定。若产品允许规范化，可以接受后保存为 zh-CN；若接口契约要求严格字面格式，则应在文档中说明规则并返回可理解的校验提示。

把校验结果变成可追踪的契约

做国际化相关开发最容易踩的坑就是把「标签解析成功」直接等同于「业务上完全可用」。在接口入口处用Locale.Builder拦截掉格式错误的输入，后续再用资源包配置确认当前系统支持的可用语言，分别存储规范化后的标签值和回退原因记录，界面展示的时候就不会出现用户遇到莫名奇妙的语言突然跳变的问题。上线前验证至少要覆盖三个环节：标签格式校验逻辑、资源匹配命中逻辑、本地化展示逻辑。