How to Add a New Language in an ASP.NET Zero Angular Application

Introduction

This document provides step-by-step instructions for adding a new localization (language) in your ASP.NET Zero Angular application. Localization allows users to interact with the application in their preferred language, thereby improving usability and accessibility. For more details on localization in ASP.NET Boilerplate, refer to the official documentation: ASP.NET Boilerplate Localization.

Steps to Add a New Language

1. Register the New Language in the Backend

To support a new language in the backend, you need to register it in the DefaultLanguagesCreator.cs file located under Migrations/Seed/Host in the YourProjectName.EntityFrameworkCore project.

Modify DefaultLanguagesCreator.cs

In this step, you need to add the new language to the list of initial languages registered in the system. This ensures that the application recognizes the new language and makes it available for selection. Modify the GetInitialLanguages method to include the new language code, display name, and flag icon.

DefaultLanguagesCreator.cs

public class DefaultLanguagesCreator
{
    public static List<ApplicationLanguage> InitialLanguages => GetInitialLanguages();

    private readonly AbpZeroTemplateDbContext _context;

    private static List<ApplicationLanguage> GetInitialLanguages()
    {
        var tenantId = AbpZeroTemplateConsts.MultiTenancyEnabled ? null : (int?)1;
        return new List<ApplicationLanguage>
            {
                new ApplicationLanguage(tenantId, "en", "English", "famfamfam-flags us"),
                new ApplicationLanguage(tenantId, "pl", "Polski", "famfamfam-flags pl"),
                //Other languages
            };
    }

    //...
}

In the code above:

• "pl" is the language code for Polish.
• "Polski" is the display name.
• "famfamfam-flags pl" refers to the flag icon for Polish.

Create the Localization XML File

The localization XML file contains key-value pairs for translating text within the application. Each language has its own XML file where you define translations for UI elements, messages, and labels. This file ensures that the application can display content in the selected language. Create a new localization file next to the existing ones, in the Localization/YourProjectName folder of the YourProjectName.Core project.

YourProjectName-pl.xml

<?xml version="1.0" encoding="utf-8" ?>
<localizationDictionary culture="pl">
  <texts>
    <text name="HomePage">Strona główna</text>
    <text name="Logout">Wyloguj się</text>
    <!-- Add other translations here -->
  </texts>
</localizationDictionary>

2. Add Language to Angular

To fully support the new language in the Angular UI, you need to update various localization settings, including date picker localization.

Configure Locale for ng-zorro Components

ASP.NET Zero's Angular UI uses ng-zorro components (date pickers, tables, pagination etc.), which carry their own localized texts. Two places must know about the new language:

Register the Locale

Add the new language to src/shared/utils/ng-zorro-locales.ts. ng-zorro ships every locale from the ng-zorro-antd/i18n entry point; only the locales listed in this file are included in the application bundle:

import {
    en_US,
    pl_PL, // Add import for the new language here
    // Other locales
} from 'ng-zorro-antd/i18n';

export const NG_ZORRO_LOCALES: Record<string, NzI18nInterface> = {
    en_US,
    pl_PL, // Add the new language here
    // Other locales
};

Map the Language to the ng-zorro Locale

Add a mapping to the localeMappings.ngZorro array in src/assets/appconfig.json (and in the appconfig.production.json / appconfig.k8s.json variants), so the ABP language name resolves to the ng-zorro locale key:

"ngZorro": [
    {
        "from": "pl",
        "to": "pl_PL"
    }
]

At startup, the application resolves the current ABP language through this mapping and registers the matching locale via NzI18nService, so ng-zorro components - including date pickers - display their texts and date formats in the selected language. If no mapping or locale is found, English is used as the fallback.

3. Verify and Test the Localization Changes

After implementing the necessary changes, follow these steps to verify that the new language is properly integrated into the application:

• Restart the Application
  • Restart both the backend and frontend to ensure that all localization changes take effect.
• Select the New Language
  • In your app, select the newly added language from the language selection drop-down menu and verify that user interface elements such as menus and labels are updated appropriately.
• Test Date Localization
  • Open any date pickers and confirm that dates are displayed in the correct format for the selected language.

Note: The newly added language and its XML content are stored in the database when the application runs.

Conclusion

By following these steps, you have successfully added support for a new language in your ASP.NET Zero Angular application. The localization process ensures that both backend and frontend components, including UI elements and date pickers, properly reflect the new language.

For more information, refer to the official documentation:

• ASP.NET Boilerplate Localization.
• ASP.NET Zero Language Management.