多语言
XinAdmin 内置完整的多语言方案,覆盖前端(React + react-i18next)和后端(Laravel),支持中英文双语言,并可通过简单配置扩展更多语言。
整体架构
前端通过 react-i18next 管理 UI 文本,切换语言时同步更新 Ant Design 组件和 dayjs 日期库的 locale;后端通过 LanguageMiddleware 中间件检测请求语言,使用 Laravel 的 __() 辅助函数返回对应语言的文本。
前端多语言
技术栈
目录结构
i18next 初始化
入口文件 main.tsx 顶层导入该模块,确保 i18next 在应用渲染前完成初始化。
语言选项配置
资源汇总导出
每个 locale 目录内有自己的 index.ts 做 barrel export,将所有模块的翻译键值合并到一个对象中。
翻译文件格式
每个模块文件导出一个对象,key 使用点号分隔的命名空间:
支持 {{variable}} 插值语法。
翻译文件命名规范
useLanguage Hook
核心语言切换逻辑封装在 useLanguage hook 中:
切换语言时同步更新三个层面:
- dayjs locale — 日期格式化
- i18next language — UI 文本
- localStorage — 持久化存储
AntdProvider 集成
LanguageSwitcher 组件
在顶栏头部渲染,用户点击图标即可切换语言。
在组件中使用翻译
Axios 请求拦截器
每次 API 请求自动附带当前语言到 User-Language 请求头:
添加新语言(前端)
以添加日语为例:
1. 创建翻译文件目录
2. 更新语言选项
3. 注册到资源映射
后端多语言
配置
环境变量默认值可通过 .env 文件覆盖:
目录结构
翻译文件格式
采用 Laravel 标准 PHP 数组格式:
嵌套数组使用点号访问:
翻译文件分类
LanguageMiddleware 中间件
语言检测的优先级链(从高到低):
CORS 配置
AllowCrossDomainMiddleware 显式允许 User-Language 头跨域传输:
在控制器中使用
添加新语言(后端)
以添加日语为例:
1. 创建语言文件
复制全部 6 个文件到 lang/ja/ 并翻译为日语。
2. 注册到中间件
注意:前端
options.ts中的value值必须与中间件supportedLanguages的 key 一致,否则中间件无法匹配。
前后端数据流
完整的一次多语言请求流程:
最佳实践
1. Key 命名规范
- 前端:
模块.页面.字段格式,如sysUserList.username、layout.headerHeight - 后端:
文件名.嵌套键格式,如user.login_success、system.file.upload_failed - 中英文 key 保持一致,方便对照和补全
2. 插值使用
3. 文本管理
- 每个功能模块独立翻译文件,避免单文件过大
- 新增翻译 key 时同步更新所有语言文件,至少保留英文作为 fallback
- 定期清理不再使用的 key
4. 语言切换优化
- 语言偏好持久化到
localStorage,刷新页面不丢失 - 切换语言后无需刷新页面,React 自动重渲染
useMemo缓存 antdLocale,避免不必要的重新计算
5. 国际化支持建议
如需扩展到更多语言,建议按以下顺序处理:
- 先补充英文翻译(作为 fallback 语言)
- 同步更新前端
options.ts和后端LanguageMiddleware.supportedLanguages - 添加对应的
antdlocale 和dayjslocale - 测试语言切换后 Ant Design 组件、日期格式和 API 返回文本是否正常