多语言系统化设计与实现原理

原创已于 2025-05-06 13:42:32 修改 · 1.5k 阅读

本内容遵循CC 4.0 BY-SA版权协议

于 2025-03-11 10:51:54 首次发布

内测之家
一款功能强大且全面的应用内测与管理平台、分发平台，专为安卓（Android）、苹果（iOS）、纯血鸿蒙（HarmonyNext）开发者打造，旨在为用户提供便捷高效、安全可靠的一站式服务。无论是从资源安全到传输安全，还是从数据保护到应用管理、统计分析，内测之家都展现出卓越的能力与优势。

一、核心需求与实现目标

在多语言（i18n）设计中，需满足以下需求：。

动态适配：根据用户语言环境返回对应语言的文本。
灵活性：支持静态文本（如按钮标签）和动态内容（如商品名称）。
易维护性：语言资源可扩展、可集中管理。
性能优化：减少实时解析开销，提升响应速度。

二、三种主流实现方案对比

方案	JSON字段存储	字典表管理	Resource Bundle
适用场景	动态内容（用户生成数据、商品名）	系统级配置（国家列表、状态码）	静态文本（按钮标签、错误提示）
存储形式	数据库字段存储JSON格式	数据库表存储键值对	本地文件（.properties）
优点	- 灵活更新 - 支持复杂结构	- 集中管理 - 易于扩展新语言	- 加载速度快 - 语言分层清晰
缺点	- 解析开销大 - 结构复杂	- 依赖数据库查询 - 性能瓶颈	- 无法动态修改 - 需重启生效
示例	`{"zh-CN":"商品名","en-US":"Name"}`	`sys_i18n` 表存储键值对	`messages_zh_CN.properties`

三、JSON字段存储方案

1. 实现原理

数据存储：在数据库字段中存储多语言内容的JSON结构。
动态解析：根据用户语言标识提取对应值。

2. 使用场景

商品多语言名称、描述。
用户生成内容（如评论、动态）。

3. 代码示例（Java + Spring）

public class I18nJsonHandler implements I18nHandler {

    private static final String MODE = "json";

    @Override
    public String fetchMode() {
        return MODE;
    }

    @Override
    public String process(String fieldValue, Locale locale, I18n i18n) {
        Map<String, String> translations = JsonUtils.jsonToMap(fieldValue, String.class);
        if (translations == null || translations.size() == 0) {
            return null;
        }
        final String lang = locale.toLanguageTag();
        String value = translations.get(lang);
        if (StringUtils.isBlank(value)) {
            final String[] langItems = lang.split("-");
            if (langItems.length >= 2) {
                value = translations.get(langItems[0]);
            }
        }
        return value;
    }
}

4. 优缺点

优点：适合频繁更新的动态内容，支持嵌套结构。
缺点：需手动解析JSON，性能较低。

四、字典表管理方案

1. 实现原理

数据库设计：创建字典表（如 sys_i18n），存储多语言键值对。
键值映射：通过 模块名 + 键名 + 语言 唯一标识一条记录。

2. 使用场景

国家/地区列表。
系统状态码多语言描述。

3. 数据库表结构

字段	说明
`module`	模块名（如 "country"）
`key`	键名（如 "CN"）
`lang`	语言标识（如 "zh-CN"）
`value`	对应语言的值（如 "中国"）

4. 代码示例

-- 查询中国的多语言名称
SELECT value FROM sys_i18n 
WHERE module = 'country' AND key = 'CN' AND lang = 'en-US';
-- 返回 "China"

5. 优缺点

优点：集中管理，适合全局配置。
缺点：高频查询时需优化缓存机制。

五、Resource Bundle 方案

1. 实现原理

文件化管理：按语言拆分 .properties 文件，键值对存储静态文本。
分层加载：根据 Locale 自动匹配最接近的资源文件。

2. 使用场景

界面标签（如按钮、菜单）。
预定义错误提示（如“参数无效”）。

3. 文件示例

login.mode.not.support=登录方式不支持
account.format.invalid=账号格式无效
password.not.match.reg=密码规则不匹配
password.error=密码错误
password.not.set.yet=密码未设置
username.or.password.error=账号或密码错误
captcha.error=验证码错误
verify.code.error=验证码错误
oauth.need.bind.account=授权需要绑定账号
oauth.login.error=授权登录失败
no.authority.access.app=无权访问
user.locked=账号已锁定

4. 技术实现（Java + Spring）

public class I18nMessages extends ResourceBundleMessageSource {
    private static final I18nMessages INSTANCE = new I18nMessages();

    public static I18nMessages get() {
        return INSTANCE;
    }

    public String getMessage(String key, Object... arguments) {
        return super.getMessage(key, arguments, key, LocaleContextHolder.getLocale());
    }
}

public class I18nCodeHandler implements I18nHandler{
    private static final String[] emptyArray = new String[0];
    private static final String MODE = "code";

    private final I18nMessages i18nMessages;

    public I18nCodeHandler(I18nMessages i18nMessages) {
        this.i18nMessages = i18nMessages;
    }

    @Override
    public String fetchMode() {
        return MODE;
    }

    @Override
    public String process(String fieldValue, Locale locale, I18n i18n) {
        return i18nMessages.getMessage(fieldValue, emptyArray, fieldValue, locale);
    }
}

5. 优缺点

优点：性能高，语言分层清晰。
缺点：修改需更新文件并重启服务。

六、具体切面处理逻辑

1.获取客户端的【`Accept-Language】的值写入多语言上下文中`

public class I18nInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String requestMethod = request.getMethod();
        if (requestMethod.equalsIgnoreCase(HttpMethod.OPTIONS.name())) {
            return true;
        }

        if (handler instanceof HandlerMethod) {
            final Locale locale = I18nUtils.getLocale();
            //放在线程局部变量
            LocaleContextHolder.setLocale(locale);
        }
        return  true;
    }

}

2.Body切面处理逻辑

package com.forsoo.common.web.i18n.advice;

import com.forsoo.common.domain.Result;
import com.forsoo.common.util.JsonUtils;
import com.forsoo.common.util.StringUtils;
import com.forsoo.common.web.constant.Constant;
import com.forsoo.common.web.i18n.I18nMessages;
import com.forsoo.common.web.i18n.annotations.I18n;
import com.forsoo.common.web.i18n.handler.I18nHandler;
import com.forsoo.common.web.i18n.handler.I18nHandlerManager;
import jakarta.annotation.Resource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.core.MethodParameter;
import org.springframework.core.annotation.Order;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import java.lang.reflect.Field;
import java.text.MessageFormat;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

/**
 * @author kingchange
 * @title I18nAdvice
 * @date 2024/5/11 11:02
 */
@Order(Constant.AdviceOrder.I18n)
@ControllerAdvice
public class I18nAdvice implements ResponseBodyAdvice<Result> {
    private static final String[] emptyArray = new String[0];

    @Resource
    private I18nMessages i18nMessages;
    @Autowired
    private I18nHandlerManager i18nHandlerManager;
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    @Override
    public Result beforeBodyWrite(Result body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        String renderMsg = null;
        final Locale locale = LocaleContextHolder.getLocale();
        //有国际化配置的才会替换
        if (locale != null) {
            // 处理 message 的多语言
            if (StringUtils.isNotBlank(body.getMessage())) {
                renderMsg = i18nMessages.getMessage(body.getMessage(), body.getArgs() == null ? emptyArray : body.getArgs(), null, locale);
            }
            // 处理 data 的多语言
            processI18nInData(body.getData(), locale);
        }
        // 原信息返回
        if (StringUtils.isBlank(renderMsg)){
            renderMsg = body.getMessage();
        }
        // 有额外参数，则格式化
        if (body.getArgs() != null && body.getArgs().length > 0 && StringUtils.isNotBlank(renderMsg)){
            renderMsg = MessageFormat.format(body.getMessage(), body.getArgs());
        }
        body.setMessage(renderMsg);
        body.setArgs(null);

        return body;
    }

    private Object processI18nInData(Object data, Locale locale) {
        if (data == null) {
            return data;
        }

        if (data instanceof List lst) {
            return lst.stream().map((element) -> {
                return this.processI18nInData(element, locale);
            }).collect(Collectors.toList());
        } else if (data instanceof Set set) {
            return set.stream().map((element) -> {
                return this.processI18nInData(element, locale);
            }).collect(Collectors.toSet());
        } else if (data instanceof Map ) {
            Map<?, ?> map = (Map)data;
            return map.entrySet().stream().collect(Collectors.toMap((entry) -> {
                return entry.getKey();
            }, (entry) -> {
                return this.processI18nInData(entry.getValue(), locale);
            }));
        }
        return translateObjectFields(data, locale);
    }

    private Object translateObjectFields(Object object, Locale locale) {
        if (object == null) {
            return object;
        }
        if (!object.getClass().isAnnotationPresent(I18n.class)) {
            return object;
        }

        Class<?> clazz = object.getClass();
        while (clazz != null) {
            for (Field field : clazz.getDeclaredFields()) {
                if (!field.isAnnotationPresent(I18n.class)) {
                    continue;
                }
                // 设置私有属性可访问
                field.setAccessible(true);
                try {
                    Object fieldValue = field.get(object);
                    if (fieldValue instanceof String strValue) {
                        // 对String类型字段进行国际化处理
                        final I18n i18n = field.getAnnotation(I18n.class);
                        String i18nValue = processI18n(strValue, locale, i18n);
                        field.set(object, i18nValue);
                    } else {
                        // 如果字段是对象类型，则递归处理
                        processI18nInData(fieldValue, locale);
                    }
                    // 可以根据需要处理其他类型或进行递归翻译
                } catch (IllegalAccessException e) {
                    e.printStackTrace();
                }
            }
            // 移动到父类
            clazz = clazz.getSuperclass();
        }
        return object;
    }

    private String processI18n(String fieldValue, Locale locale, I18n i18n){
        if (StringUtils.isBlank(fieldValue)){
            return fieldValue;
        }
        final I18nHandler i18nHandler = i18nHandlerManager.getHandler(i18n.value());
        if (i18nHandler == null){
            return fieldValue;
        }
        return i18nHandler.process(fieldValue, locale, i18n);
    }
}

七、选型建议与最佳实践

1. 选型依据

项目规模	推荐方案
小型项目	Resource Bundle（简单高效）
中大型项目	混合架构（静态文本 + 动态内容）
全球化平台	字典表 + 分布式缓存（如Redis）

2. 最佳实践

前后端协作：
- 前端传递 Accept-Language 头部。
- 后端统一处理多语言逻辑。
缓存优化：
- 使用内存缓存（如Caffeine）加速Resource Bundle加载。
- 对字典表查询结果进行二级缓存（如Redis + LocalCache）。
热更新支持：
- 使用 ReloadableResourceBundleMessageSource 支持文件热加载。
- 通过消息队列通知服务更新字典表缓存。