foodie-server/docs/superpowers/specs/2026-09-07-backend-thai-i18n-design.md

后端泰语提示支持设计

目标

在不改变现有默认语言的前提下，为后端系统提示增加完整泰语支持。默认语言继续使用台湾繁体中文 zh_TW；只有请求或用户语言明确选择泰语时才返回泰语提示。

本阶段仅处理后端系统消息，包括同步接口错误/成功提示，以及通过用户语言生成的推送和异步通知。平台管理端、商家管理端、App 页面文案，以及商品和门店等业务数据的泰语字段不在本阶段范围内。

语言代码

• 后端标准 Locale：th_TH。
• 同时接受客户端常见写法：th_TH、th-TH、th。
• 上述三种写法统一解析为泰国地区泰语 Locale。
• 默认 Locale 保持 zh_TW，未知、空白或非法语言代码仍回退台湾繁体中文。
• 现有 zh_CN、zh_TW、en_US 和 vi 行为必须保持兼容。

语言资源

新增 ruoyi-admin/src/main/resources/i18n/messages_th_TH.properties，以现有完整语言包为键集合，翻译所有后端提示，而不是只翻译闪送模块。

要求：

• 泰语包与 messages_zh_CN.properties、messages_zh_TW.properties、messages_en_US.properties、messages_vi.properties 的消息 key 完全一致。
• 占位符名称、数量和顺序保持一致，例如 {0}、{1} 不得在翻译中丢失或调换语义。
• 技术标识、订单号、HTTP、URL、PIN、TWD 等不可翻译的内容保持原义。
• 缺失 key 仍由 Spring 的基础资源包回退，但契约测试必须阻止正常提交出现缺失 key。

Locale 解析和消息流

同步 HTTP 请求

保留现有 SessionLocaleResolver 和 LocaleChangeInterceptor，参数名继续使用 lang。拦截器通过同一个白名单解析器规范化语言代码，因此客户端使用 ?lang=th_TH、?lang=th-TH 或 ?lang=th 都会得到泰国地区泰语 Locale。默认 Locale 继续设置为台湾繁体中文。

用户语言和异步消息

修复 LocaleUtils.parseLocale() 当前无条件返回台湾繁体 Locale 的问题，改为白名单解析：

• 简体中文：zh_CN、zh-CN、zh
• 台湾繁体：zh_TW、zh-TW、tw
• 英文：en_US、en-US、en
• 越南语：vi_VN、vi-VN、vi
• 泰语：th_TH、th-TH、th

无法识别的值返回台湾繁体默认 Locale，不允许任意 Locale 绕过受支持语言范围。getUserLocale() 继续从现有 Redis 用户语言值读取并调用该解析器，使推送和异步通知可以使用泰语。

本阶段不修改 toLangCode() 和 getUserLanguageCode() 的数字语言映射，因为它们用于商品、门店等业务数据语言选择，而泰语业务数据尚未纳入范围。这样可以避免把泰语错误映射到现有数据列。

错误处理与兼容性

• 请求未指定语言：返回台湾繁体提示。
• 请求指定支持的泰语代码：返回泰语提示。
• 用户保存泰语偏好：异步通知使用泰语提示。
• 请求传入未知语言：回退台湾繁体提示，不抛出语言解析异常。
• 泰语资源中缺少消息 key：Spring 可回退基础资源，但语言包契约测试应在交付前发现该问题。

验证

新增或扩展测试，至少覆盖：

1. 五个受支持的本地化语言包（zh_CN、zh_TW、en_US、vi、th_TH）key 集合一致，泰语包包含全部现有后端消息 key。
2. th_TH、th-TH、th 都解析为泰国地区泰语。
3. 空值、未知语言仍解析为 zh_TW。
4. 现有简中、繁中、英文、越南语解析保持正确。
5. 从 Spring MessageSource 读取典型通用提示和闪送提示时返回泰语，并正确替换参数占位符。
6. 使用 JDK 21 运行受影响模块的定向测试和编译。

非目标

• 不新增数据库泰语字段或数字语言代码。
• 不翻译商品、分类、门店、活动等业务数据。
• 不修改平台管理端、商家管理端或 App 的语言选择界面。
• 不改变默认语言；默认始终为台湾繁体中文。