跳到主要内容
版本：Next

多语言与本地化

本文档引用的文件

目录​

  1. 简介
  2. 多语言配置结构
  3. 本地化资源类的作用
  4. 资源文件的组织结构
  5. 本地化文本的获取方式
  6. 新增语言支持的操作步骤
  7. 语言切换机制
  8. 总结

简介​

本项目基于ABP框架实现多语言支持（i18n），通过标准的本地化机制为插件提供国际化能力。系统支持在领域异常、应用服务和用户界面提示等场景中动态获取对应语言的文本内容，确保用户在不同语言环境下获得一致的体验。

多语言配置结构​

项目中的多语言资源配置集中于 CMS.Plugin.MyPluginName.Domain.Shared 模块下的 Localization/MyPluginName 目录中，包含以下核心组成部分：

  • MyPluginNameResource.cs：定义本地化资源的命名空间
  • en.json：英文语言资源文件
  • zh-Hans.json：简体中文语言资源文件

该结构遵循ABP框架的本地化规范，便于统一管理和扩展。

Diagram sources

Section sources

本地化资源类的作用​

MyPluginNameResource 类作为本地化键的命名空间标识，其主要作用如下：

  • 通过 [LocalizationResourceName("MyPluginName")] 特性声明资源名称
  • 为所有与该插件相关的本地化键提供统一的命名空间前缀
  • 在调用 IStringLocalizer 或 ILocalizationManager 时作为资源定位的关键标识

此设计确保了本地化键的隔离性，避免与其他模块发生冲突。

Section sources

资源文件的组织结构​

每个语言资源文件采用标准JSON格式，包含以下结构：

{
  "culture": "en",
  "texts": {
    "DisplayName:SCMS.AppSettings.MyPluginName.PluginState": "MyPluginName plugin state",
    "CMS.Plugin.MyPluginName:NameAlreadyExists": "The '{0}' name already exists, please re-enter it !"
  }
}

其中：

  • culture 字段标明当前语言文化标识
  • texts 对象包含所有本地化键值对
  • 键名通常采用命名空间前缀 + 语义描述的方式，如 CMS.Plugin.MyPluginName:NameAlreadyExists
  • 支持占位符 {0}, {1} 等用于动态参数插入

中文资源文件 zh-Hans.json 与英文文件结构完全一致，仅翻译对应文本内容。

Section sources

本地化文本的获取方式​

在领域异常中使用​

通过 CMSPluginDomainErrorCodes 定义错误码，并结合本地化资源实现多语言异常消息输出。例如：

throw new BusinessException(CMSPluginDomainErrorCodes.NameAlreadyExists, name);

框架会自动查找 MyPluginName 资源中对应键的本地化文本并替换参数。

在应用服务中注入 IStringLocalizer​

在应用服务类中可通过依赖注入获取本地化器：

public class MyEntityNameAppService : CMSPluginAppService, IMyEntityNameAppService
{
    private readonly IStringLocalizer<MyPluginNameResource> _localizer;

    public MyEntityNameAppService(IStringLocalizer<MyPluginNameResource> localizer)
    {
        _localizer = localizer;
    }

    public string GetLocalizedMessage()
    {
        return _localizer["DisplayName:SCMS.AppSettings.MyPluginName.PluginState"];
    }
}

通过 ILocalizationManager 获取​

对于需要动态指定资源名称的场景，可使用 ILocalizationManager：

var manager = context.GetService<ILocalizationManager>();
var text = manager.GetString("MyPluginName", "CMS.Plugin.MyPluginName:NameAlreadyExists", name);

上述机制确保在领域层、应用服务层和UI层均可灵活获取本地化文本。

Section sources

新增语言支持的操作步骤​

1. 创建新的语言资源文件​

在 Localization/MyPluginName 目录下创建新语言的JSON文件，如 fr.json（法语）或 de.json（德语）：

{
  "culture": "fr",
  "texts": {
    "DisplayName:SCMS.AppSettings.MyPluginName.PluginState": "État du plugin MyPluginName",
    "CMS.Plugin.MyPluginName:NameAlreadyExists": "Le nom '{0}' existe déjà, veuillez le saisir à nouveau !"
  }
}

2. 更新 ABP 配置​

确保模块配置中已启用多语言支持。在 CMSPluginDomainModule 中确认已依赖 AbpLocalizationModule（由 AbpDddDomainModule 自动包含）。

3. 配置支持的文化列表​

在主应用程序的 appsettings.json 或模块配置中添加支持的文化：

"AbpLocalization": {
  "Languages": [
    {
      "Culture": "zh-Hans",
      "UiCulture": "zh-Hans",
      "DisplayName": "简体中文"
    },
    {
      "Culture": "en",
      "UiCulture": "en",
      "DisplayName": "English"
    },
    {
      "Culture": "fr",
      "UiCulture": "fr",
      "DisplayName": "Français"
    },
    {
      "Culture": "de",
      "UiCulture": "de",
      "DisplayName": "Deutsch"
    }
  ]
}

4. 设置默认语言​

在配置中指定默认语言：

"DefaultLanguage": "zh-Hans"

完成以上步骤后，系统即可识别并加载新语言资源。

Section sources

语言切换机制​

默认语言切换​

系统启动时根据配置文件中的 DefaultLanguage 设置默认语言。用户首次访问时将自动使用该语言显示界面内容。

运行时语言变更​

运行时语言变更可通过以下方式实现：

  • 基于用户偏好设置：将用户选择的语言存储在数据库或配置中，在每次请求时读取并设置当前文化
  • URL 参数传递：通过 /lang=zh-Hans 或 /en 等路由参数动态切换
  • HTTP Header 检测：根据浏览器 Accept-Language 头自动匹配最接近的语言
  • ABP 内置语言切换接口：调用 ILanguageProvider 和 ICurrentCultureSetter 实现程序化切换

ABP 框架会在每个请求上下文中维护当前文化信息，并确保所有本地化服务返回对应语言的文本。

Section sources

总结​

本项目通过 ABP 框架提供的强大本地化机制，实现了完整的多语言支持。MyPluginNameResource 作为资源命名空间，配合结构化的 JSON 资源文件，使得本地化文本管理清晰且易于扩展。开发者可在领域异常、应用服务和 UI 层通过标准 API 获取本地化文本。新增语言仅需添加资源文件并更新配置，具备良好的可维护性和扩展性。