工程国际化踩坑实录-写博客的第二天

1. 前言：从CRUD到国际化的挑战

转眼间，来公司快两年了。回头看，除了日常的业务CRUD，其实让我最有成就感的，就是独立负责并搭建了项目的国际化框架。这是我第一次完整主导一个工程，从需求评估到资源调度再到落地上线，期间遇到了不少“天坑”，也收获了很多成长。

2. 国际化框架搭建：从懵圈到沉淀

2.1 项目背景

所谓工程国际化，其实就是让原本只面向国内用户的系统，能够适配不同国家和地区的语言、流程和习惯。比如界面提示词、异常信息的多语言支持，以及业务流程的差异（如国内用手机号，海外用邮箱等）。

刚接到这个需求时，我其实挺懵的——刚毕业没多久，突然要主导这样一个全新的项目，还要协调前端、测试、设计等各方资源，感觉像是“刚毕业就当PM”了，既兴奋又忐忑。但也正因为如此，我成长得飞快。

2.2 技术方案的选择与迭代

最初，我和导师讨论，是不是可以“国内+海外一套代码”，通过配置文件（比如yml）区分环境，然后在代码中用if-else分支做不同逻辑处理。异常提示则用枚举+Spring国际化框架来实现。

一开始，这种方式看起来还行。但随着海外需求的增加，业务逻辑分歧越来越大，if-else越来越多，代码变得臃肿不堪，维护极其困难。那段时间，每次review自己的代码都想吐槽一句：“狗都不看！”

最终，我们决定单独维护一个intl分支，把所有国际化相关的修改都放在这里。虽然需要维护两套代码，但项目结构清晰了很多，定位和解决bug的效率也提升了不少。更重要的是，这种分离让团队协作、后续扩展都变得简单起来。

3. 国际化三大“天坑”详解

3.1 国家简写不一致——生产事故的教训

第一个大坑就是国家简写不一致。Spring国际化框架里，印尼语的国家简写是in，而我们数据库用的是id。这导致国际化属性无法正确覆盖默认英文字段，页面上始终显示英文内容，最终引发了一次生产事故。

为了解决这个问题，我专门写了一个工具类进行适配：

public class IntlLocaleUtils { /** * 获取当前 locale，如果是印尼语的 "in"，则返回 "id" */ public static String getLocaleString() { Locale locale = LocaleContextHolder.getLocale(); String localeString = locale.toString(); if ("in".equals(localeString)) { localeString = "id"; } return localeString; } }

通过这个小工具，将框架和数据库之间的差异成功打通，问题迎刃而解。

3.2 异常处理中的国际化失效

另一个大坑是异常处理。我们的异常信息一般通过枚举类统一管理：

public enum ConstantEnum implements ResponseCode { NO_COMPANY_INFO(44444, "无公司信息无权操作"), } public enum MsgEnum implements I18nEnum { COMPANY_DEREGISTERED("已注销公司"), }

抛出异常时直接使用：

if (req.getTkId() == null) { throw new BusinessException(ERROR_COUPON_ID_MISSING); }

大多数情况下国际化没有问题，但如果外层有大粒度的try-catch，会把自定义的国际化异常捕获掉，导致无法返回正确的多语言信息给前端。后来我们优化了异常捕获粒度，并确保即使捕获，也能继续抛出相同的国际化字段，这才彻底解决了问题。

3.3 时区问题（预告）

还有一个超级大的坑——时区问题。这个涉及JVM时区、数据库时区、目标国家时区及它们之间的偏移算法，算是整个国际化过程中最复杂、最容易踩雷的一环。后续我会专门写一篇详细分享，这里先埋个伏笔。

4. 小结与收获

回头看，这一路踩过的坑、遇到的问题，其实都是宝贵的财富。每一次生产事故、每一次线上bug，都让我对技术和工程有了更深刻的理解。
做国际化，看似只是语言适配，其实背后包含着对业务、技术、团队协作能力的全方位考验。