Skip to main content
Version: Next

Localization

Files Referenced in this Document

Table of Contents​

  1. Introduction
  2. Localization Configuration Structure
  3. Role of Localization Resource Class
  4. Resource File Organization
  5. How to Retrieve Localized Text
  6. Steps to Add New Language Support
  7. Language Switching Mechanism
  8. Summary

Introduction​

This project implements multi-language support (i18n) based on the ABP framework, providing internationalization capabilities for the plugin through standard localization mechanisms. The system supports dynamic retrieval of localized text content in scenarios such as domain exceptions, application services, and user interface prompts, ensuring consistent user experience across different language environments.

Localization Configuration Structure​

The multi-language resource configuration in the project is centralized in the Localization/MyPluginName directory under the CMS.Plugin.MyPluginName.Domain.Shared module, containing the following core components:

  • MyPluginNameResource.cs: Defines the namespace for localization resources
  • en.json: English language resource file
  • zh-Hans.json: Simplified Chinese language resource file

This structure follows the ABP framework's localization specifications, facilitating unified management and extension.

Diagram sources

Section sources

Role of Localization Resource Class​

The MyPluginNameResource class serves as the namespace identifier for localization keys. Its main roles are as follows:

  • Declares the resource name via the [LocalizationResourceName("MyPluginName")] attribute
  • Provides a unified namespace prefix for all localization keys related to this plugin
  • Serves as the key identifier for resource location when calling IStringLocalizer or ILocalizationManager

This design ensures isolation of localization keys, avoiding conflicts with other modules.

Section sources

Resource File Organization​

Each language resource file adopts standard JSON format, containing the following structure:

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

Where:

  • culture field indicates the current language culture identifier
  • texts object contains all localized key-value pairs
  • Key names typically adopt namespace prefix + semantic description, e.g., CMS.Plugin.MyPluginName:NameAlreadyExists
  • Supports placeholders {0}, {1}, etc., for dynamic parameter insertion

The Chinese resource file zh-Hans.json has a completely consistent structure with the English file, only translating corresponding text content.

Section sources

How to Retrieve Localized Text​

Using in Domain Exceptions​

Define error codes via CMSPluginDomainErrorCodes and combine with localization resources to implement multi-language exception message output. For example:

throw new BusinessException(CMSPluginDomainErrorCodes.NameAlreadyExists, name);

The framework will automatically look up the localized text for the corresponding key in the MyPluginName resource and replace parameters.

Injecting IStringLocalizer in Application Services​

In application service classes, the localizer can be obtained via dependency injection:

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"];
    }
}

Retrieving via ILocalizationManager​

For scenarios where resource names need to be dynamically specified, ILocalizationManager can be used:

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

The above mechanisms ensure flexible retrieval of localized text in the domain layer, application service layer, and UI layer.

Section sources

Steps to Add New Language Support​

1. Create New Language Resource File​

Create a JSON file for the new language in the Localization/MyPluginName directory, such as fr.json (French) or de.json (German):

{
  "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. Update ABP Configuration​

Ensure multi-language support is enabled in the module configuration. Confirm dependence on AbpLocalizationModule (automatically included by AbpDddDomainModule) in CMSPluginDomainModule.

3. Configure Supported Cultures List​

Add supported cultures in the appsettings.json of the main application or module configuration:

"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. Set Default Language​

Specify the default language in the configuration:

"DefaultLanguage": "zh-Hans"

After completing the above steps, the system can recognize and load the new language resources.

Section sources

Language Switching Mechanism​

Default Language Switching​

The system sets the default language upon startup based on the DefaultLanguage setting in the configuration file. Users will automatically use this language to display interface content upon first access.

Runtime Language Change​

Runtime language changes can be implemented in the following ways:

  • Based on User Preferences: Store the user's selected language in the database or configuration, and read and set the current culture on each request
  • URL Parameter Passing: Dynamically switch via route parameters like /lang=zh-Hans or /en
  • HTTP Header Detection: Automatically match the closest language based on the browser's Accept-Language header
  • ABP Built-in Language Switching Interface: Call ILanguageProvider and ICurrentCultureSetter to implement programmatic switching

The ABP framework maintains current culture information in each request context and ensures all localization services return text in the corresponding language.

Section sources

Summary​

This project implements complete multi-language support through the powerful localization mechanism provided by the ABP framework. MyPluginNameResource acts as the resource namespace, cooperating with structured JSON resource files to make localized text management clear and easy to extend. Developers can retrieve localized text through standard APIs in domain exceptions, application services, and the UI layer. Adding a new language only requires adding a resource file and updating the configuration, offering good maintainability and extensibility.

Last updated on