scaffold-i18n 国际化模块

模块概述

scaffold-i18n 提供基于数据库的多语言国际化解决方案。翻译数据存储在 MySQL 中，通过 DatabaseMessageSource 与 Spring 的 MessageSource 体系无缝集成。支持多语言管理（增删改查、设置默认语言）、翻译管理（增删改查、批量保存）、Redis 缓存加速和公开端点（无需认证）。前端可通过公开接口获取翻译数据，后端通过 I18nHelper 工具类在 Service 层获取国际化文本。

功能列表

• 语言管理：支持多语言的增删改查、启用/禁用、设置默认语言
• 翻译管理：翻译条目的增删改查、按 key 批量保存多语言翻译
• 数据库消息源：DatabaseMessageSource 从数据库读取翻译，替代传统的 properties 文件
• 本地缓存：5 分钟 TTL 本地缓存，减少数据库查询
• Redis 缓存：可选 Redis 缓存层，提升翻译读取性能
• 静态工具类：I18nHelper 供 Service 层静态调用获取国际化文本
• 公开端点：/v1/i18n/public/** 无需认证，前端可直接获取翻译数据

状态字段规范：

• status 字段（语言）遵循布尔语义：1 = 启用，0 = 禁用

核心组件

层	类名	职责
Controller	I18nLocaleController	语言管理接口，路径 /v1/i18n/locale
Controller	I18nTranslationController	翻译管理接口，路径 /v1/i18n/translation
Controller	I18nPublicController	公开接口（无需认证），路径 /v1/i18n/public
Service	I18nLocaleService	语言管理业务逻辑
Service	I18nTranslationService	翻译管理业务逻辑，含缓存操作
Core	DatabaseMessageSource	数据库消息源，继承 AbstractMessageSource，与 Spring 国际化体系集成
Core	I18nHelper	静态工具类，供任意层调用获取国际化文本
Entity	I18nLocale	语言实体
Entity	I18nTranslation	翻译实体
Config	I18nAutoConfiguration	自动配置类，注册 DatabaseMessageSource Bean
Config	I18nProperties	配置属性类

配置参数

配置前缀：scaffold.i18n

参数	类型	默认值	说明
enabled	boolean	true	模块开关
defaultLocale	String	zh-CN	默认语言编码
cacheTtlMinutes	Integer	30	Redis 缓存 TTL（分钟）

API 接口列表

语言管理 /v1/i18n/locale

方法	路径	说明
GET	/list	查询启用的语言列表
POST	/page	分页查询语言（参数：localeCode、localeName、pageNum、pageSize）
GET	/get/{id}	语言详情
POST	/create	创建语言
POST	/update	更新语言
POST	/delete/{id}	删除语言
POST	/set-default/{id}	设置默认语言

翻译管理 /v1/i18n/translation

方法	路径	说明
POST	/page	分页查询翻译
GET	/get/{id}	翻译详情
POST	/create	创建翻译
POST	/update	更新翻译
POST	/delete/{id}	删除翻译
POST	/batch-save	批量保存翻译（一个 key 对应多语言）
GET	/messages?localeCode=zh-CN	获取指定语言的全部翻译（Map）
POST	/sync-cache	同步翻译缓存

公开接口 /v1/i18n/public（无需认证）

方法	路径	说明
GET	/locales	获取启用的语言列表
GET	/messages	获取当前语言的翻译（通过 Accept-Language 头确定语言）

使用示例

在 Service 中获取国际化文本

@Service
public class OrderService {

    public void processOrder(Order order) {
        // 使用 I18nHelper 获取国际化文本
        String message = I18nHelper.getMessage("order.created.success", order.getOrderNo());
        log.info(message);
    }
}

在 Thymeleaf 模板中使用

<!-- Spring MessageSource 自动使用 DatabaseMessageSource -->
<p th:text="#{welcome.message}">Welcome</p>

批量保存翻译

// 一个 key 对应多语言翻译
await post('/v1/i18n/translation/batch-save', {
  key: 'order.status.pending',
  translations: {
    'zh-CN': '待处理',
    'en-US': 'Pending',
    'ja-JP': '保留中'
  }
})

前端获取翻译数据

// 公开端点，无需登录
const { data: locales } = await get('/v1/i18n/public/locales')
// locales = [{ localeCode: 'zh-CN', localeName: '简体中文' }, ...]

// 通过 Accept-Language 头获取翻译
const { data: messages } = await get('/v1/i18n/public/messages', {
  headers: { 'Accept-Language': 'en-US' }
})
// messages = { "welcome.message": "Welcome", "order.status.pending": "Pending", ... }

管理端查询和更新翻译

// 分页查询翻译
const { data } = await post('/v1/i18n/translation/page', {
  pageNum: 1,
  pageSize: 20,
  localeCode: 'zh-CN',
  key: 'order%'
})

// 更新翻译
await post('/v1/i18n/translation/update', {
  id: '1234567890',
  value: '订单已创建'
})

// 修改翻译后刷新缓存
await post('/v1/i18n/translation/sync-cache')

注意事项

• DatabaseMessageSource 继承 AbstractMessageSource，完全兼容 Spring 的 MessageSource 体系，支持 @Autowired MessageSource 注入。
• 本地缓存 TTL 为 5 分钟，通过 ConcurrentHashMap 实现，刷新间隔由 checkCacheRefresh() 控制。
• 翻译查找顺序：指定语言 -> 默认语言（zh-CN）-> 返回 key 本身。
• I18nTranslationServiceImpl 中注入 DatabaseMessageSource 时使用 @Autowired @Lazy 打破循环依赖。
• 公开端点 /v1/i18n/public/** 已加入安全模块的匿名路径白名单，无需携带 Token。
• 修改翻译后需调用 /sync-cache 接口刷新缓存，否则最长需要等待 5 分钟本地缓存过期。
• 语言编码格式遵循 BCP 47 标准，如 zh-CN、en-US、ja-JP。
• 模块启用条件：scaffold.i18n.enabled=true（默认启用）。
• 状态枚举：status 字段（语言）遵循布尔语义：1 = 启用，0 = 禁用