19 ABP Framework 本地化系统
ABP Framework 本地化系统
系统概述
ABP Framework 本地化系统基于 ASP.NET Core 本地化功能构建,提供模块化、可扩展的国际化和多语言支持基础设施,核心特点包括 JSON 格式资源文件、模块化资源组织及高级格式化功能。
系统架构
ABP 本地化系统由几个核心组件和代码实体组成,这些组件和实体负责管理资源的加载、存储和检索
- LocalizationManager:用于检索本地化字符串的核心服务。
- LocalizationResource:表示模块或域的一组翻译。
- JsonResourceProvider:从 JSON 文件加载资源。
- VirtualFileSystem:对文件访问进行抽象,允许资源嵌入或存储在磁盘上
资源文件与结构
- 格式:采用 JSON 文件存储,每个文件对应特定文化
- 结构示例:
{"culture": "en","texts": {"Menu:Organizations": "Organizations","Volo.AbpIo.Commercial:010003": "You are not the owner of this organization!","Welcome": "Welcome {0}"} }
- 关键元素:
culture
:语言/文化代码(如 “en”、“zh-Hans”)texts
:本地化键值对字典- 支持参数化消息(如
{0}
)、分层命名空间键(如Menu:Organizations
)和错误代码键(如Volo.AbpIo.Commercial:010003
)
模块化资源组织
- 每个模块(如 Commercial、Admin)管理自身的翻译资源
- 模块可独立进行本地化和更新
- 应用可按需包含所需模块和语言
多语言与文化支持
支持多种语言和文化,通过为每种文化代码提供资源文件实现,部分支持的语言及对应文化代码:
语言 | 文化代码 | 示例文件路径 |
---|---|---|
英语 | en | Commercial/Localization/Resources/en.json |
土耳其语 | tr | Commercial/Localization/Resources/tr.json |
简体中文 | zh-Hans | Commercial/Localization/Resources/zh-Hans.json |
繁体中文 | zh-Hant | Commercial/Localization/Resources/zh-Hant.json |
阿拉伯语 | ar | Commercial/Localization/Resources/ar.json |
英式英语 | en-GB | Commercial/Localization/Resources/en-GB.json |
本地化键模式
模式类型 | 示例键 | 示例值/用法 |
---|---|---|
简单键 | OrganizationManagement | Organization Management |
分层键 | Menu:Organizations | Organizations |
命名空间错误键 | Volo.AbpIo.Commercial:010003 | You are not the owner of this organization! |
动态/参数化键 | {0}WillBeRemovedFromDevelopers | {0} Will be removed from developers, do you confirm? |
高级功能
- 参数化消息:使用
{0}
、{1}
等占位符支持运行时替换,如"LicenseExtendMessage": "Your license end date is extended to {0}"
- HTML 字符串:本地化值可包含 HTML 标记用于 UI 渲染,如
"IndexPageHeroSection": "<span class=\"first-line\">A complete</span>..."
- 复数形式:支持复数表达,如
"discountForYears": "{0}% discount for {1} year(s)"
- 动态键:支持参数化键用于动态查找
应用集成
- 通过
IStringLocalizer
接口作为获取本地化字符串的主要入口 - 所有层(UI、应用、领域)可通过统一方式访问本地化资源
最佳实践
- 按模块组织资源,保持模块化
- 使用一致的键命名约定
- 利用分层键( colon 分隔)处理具有自然层次的 UI 元素
- 对动态内容使用参数化消息,而非字符串拼接
- 对错误消息考虑使用命名空间错误代码以保持一致性