Skip to content

Commit c59b00c

Browse files
oguzhanagiroguzhanagir
committed
Add documentation for adding new localization
1 parent ac785bc commit c59b00c

2 files changed

Lines changed: 224 additions & 0 deletions

File tree

‎docs/en/Adding-New-Localization-Angular.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# How to Add a New Language in an ASP.NET Zero Angular Application
2+
3+
## Introduction
4+
5+
This document provides step-by-step instructions for adding a new localization (language) in your ASP.NET Zero Angular application.
6+
Localization allows users to interact with the application in their preferred language, thereby improving usability and accessibility.
7+
For more details on localization in ASP.NET Boilerplate, refer to the official documentation: [ASP.NET Boilerplate Localization](https://aspnetboilerplate.com/Pages/Documents/Localization).
8+
9+
## Steps to Add a New Language
10+
11+
### 1. Register the New Language in the Backend
12+
13+
To support a new language in the backend, you need to register it in the `DefaultLanguagesCreator.cs` file located in the `YourProjectName.Core` project.
14+
15+
#### Modify DefaultLanguagesCreator.cs
16+
17+
In this step, you need to add the new language to the list of initial languages registered in the system.
18+
This ensures that the application recognizes the new language and makes it available for selection.
19+
Modify the `GetInitialLanguages` method to include the new language code, display name, and flag icon.
20+
21+
**DefaultLanguagesCreator.cs**
22+
```c#
23+
public class DefaultLanguagesCreator
24+
{
25+
public static List<ApplicationLanguage> InitialLanguages => GetInitialLanguages();
26+
27+
private readonly AbpZeroTemplateDbContext _context;
28+
29+
private static List<ApplicationLanguage> GetInitialLanguages()
30+
{
31+
var tenantId = AbpZeroTemplateConsts.MultiTenancyEnabled ? null : (int?)1;
32+
return new List<ApplicationLanguage>
33+
{
34+
new ApplicationLanguage(tenantId, "en", "English", "famfamfam-flags us"),
35+
new ApplicationLanguage(tenantId, "pl", "Polski", "famfamfam-flags pl"),
36+
//Other languages
37+
};
38+
}
39+
40+
//...
41+
}
42+
```
43+
44+
In the code above:
45+
46+
- "pl" is the language code for Polish.
47+
- "Polski" is the display name.
48+
- "famfamfam-flags pl" refers to the flag icon for Polish.
49+
50+
#### Create the Localization XML File
51+
52+
The localization XML file contains key-value pairs for translating text within the application.
53+
Each language has its own XML file where you define translations for UI elements, messages, and labels.
54+
This file ensures that the application can display content in the selected language.
55+
Create a new localization file in the **Localization** folder of the `YourProjectName.Core` project.
56+
57+
**YourProjectName-pl.xml**
58+
```xml
59+
<?xml version="1.0" encoding="utf-8" ?>
60+
<localizationDictionary culture="pl">
61+
<texts>
62+
<text name="HomePage">Strona główna</text>
63+
<text name="Logout">Wyloguj się</text>
64+
<!-- Add other translations here -->
65+
</texts>
66+
</localizationDictionary>
67+
```
68+
69+
### 2. Add Language to Angular
70+
71+
To fully support the new language in the Angular UI, you need to update various localization settings, including date picker localization.
72+
73+
#### Configure Date Localization in ngx-bootstrap
74+
75+
To ensure that the ngx-bootstrap date picker supports the new language, update the `ngx-bootstrap-datepicker-config.service.ts` file.
76+
This configuration allows the date picker to display dates in the correct format for the selected language.
77+
78+
**Import the Locale**
79+
80+
Add the new language locale to the imports from `ngx-bootstrap/chronos`:
81+
82+
```javascript
83+
import {
84+
enGbLocale,
85+
plLocale, // Add import for the new language here
86+
//Other locales
87+
} from 'ngx-bootstrap/chronos';
88+
```
89+
90+
**Update the `registerNgxBootstrapDatePickerLocales` Method**
91+
92+
Modify the method to include the new language inside the locales object:
93+
94+
```javascript
95+
static registerNgxBootstrapDatePickerLocales(): Promise<boolean> {
96+
if (abp.localization.currentLanguage.name === 'en') {
97+
return Promise.resolve(true);
98+
}
99+
100+
const locales: { [key: string]: any } = {
101+
'en': enGbLocale,
102+
'pl': plLocale, // Add new language here
103+
//Other languages
104+
};
105+
106+
let localeKey = abp.localization.currentLanguage.name.toLowerCase();
107+
108+
if (locales[localeKey]) {
109+
defineLocale(localeKey, locales[localeKey]);
110+
return Promise.resolve(true);
111+
}
112+
113+
return Promise.reject(`Locale ${localeKey} not found`);
114+
}
115+
```
116+
117+
This method ensures that the correct locale is loaded based on the currently selected language in the application. If the language is not found in the locales object, an error is returned.
118+
119+
### 3. Verify and Test the Localization Changes
120+
After implementing the necessary changes, follow these steps to verify that the new language is properly integrated into the application:
121+
122+
- **Restart the Application**
123+
- Restart both the backend and frontend to ensure that all localization changes take effect.
124+
- **Select the New Language**
125+
- In your app, select the newly added language from the language selection drop-down menu and
126+
verify that user interface elements such as menus and labels are updated appropriately.
127+
- **Test Date Localizatio**
128+
- Open any date pickers and confirm that dates are displayed in the correct format for the selected language.
129+
130+
> Note: The newly added language and its XML content are stored in the database when the application runs.
131+
132+
## Conclusion
133+
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.
134+
135+
For more information, refer to the official documentation:
136+
- [ASP.NET Boilerplate Localization](https://aspnetboilerplate.com/Pages/Documents/Localization).
137+
- [ASP.NET Zero Language Management](https://aspnetboilerplate.com/Pages/Documents/Zero/Language-Management).

‎docs/en/Adding-New-Localization-Mvc.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# How to Add a New Language in an ASP.NET Zero MVC Application
2+
3+
## Introduction
4+
5+
This document provides step-by-step instructions for adding a new localization (language) in your ASP.NET Zero MVC application.
6+
Localization allows users to interact with the application in their preferred language, thereby improving usability and accessibility.
7+
For more details on localization in ASP.NET Boilerplate, refer to the official documentation: [ASP.NET Boilerplate Localization](https://aspnetboilerplate.com/Pages/Documents/Localization).
8+
9+
## Steps to Add a New Language
10+
11+
### 1. Register the New Language in the Backend
12+
13+
To support a new language in the backend, you need to register it in the `DefaultLanguagesCreator.cs` file located in the `YourProjectName.Core` project.
14+
15+
#### Modify DefaultLanguagesCreator.cs
16+
17+
In this step, you need to add the new language to the list of initial languages registered in the system.
18+
This ensures that the application recognizes the new language and makes it available for selection.
19+
Modify the `GetInitialLanguages` method to include the new language code, display name, and flag icon.
20+
21+
**DefaultLanguagesCreator.cs**
22+
```c#
23+
public class DefaultLanguagesCreator
24+
{
25+
public static List<ApplicationLanguage> InitialLanguages => GetInitialLanguages();
26+
27+
private readonly AbpZeroTemplateDbContext _context;
28+
29+
private static List<ApplicationLanguage> GetInitialLanguages()
30+
{
31+
var tenantId = AbpZeroTemplateConsts.MultiTenancyEnabled ? null : (int?)1;
32+
return new List<ApplicationLanguage>
33+
{
34+
new ApplicationLanguage(tenantId, "en", "English", "famfamfam-flags us"),
35+
new ApplicationLanguage(tenantId, "pl", "Polski", "famfamfam-flags pl"),
36+
////Other languages
37+
};
38+
}
39+
40+
//...
41+
}
42+
```
43+
44+
In the code above:
45+
46+
- "pl" is the language code for Polish.
47+
- "Polski" is the display name.
48+
- "famfamfam-flags pl" refers to the flag icon for Polish.
49+
50+
#### Create the Localization XML File
51+
52+
The localization XML file contains key-value pairs for translating text within the application.
53+
Each language has its own XML file where you define translations for UI elements, messages, and labels.
54+
This file ensures that the application can display content in the selected language.
55+
Create a new localization file in the **Localization** folder of the `YourProjectName.Core` project.
56+
57+
**YourProjectName-pl.xml**
58+
```xml
59+
<?xml version="1.0" encoding="utf-8" ?>
60+
<localizationDictionary culture="pl">
61+
<texts>
62+
<text name="HomePage">Strona główna</text>
63+
<text name="Logout">Wyloguj się</text>
64+
<!-- Add other translations here -->
65+
</texts>
66+
</localizationDictionary>
67+
```
68+
69+
### 2. Verify and Test the Localization Changes
70+
After implementing the necessary changes, follow these steps to verify that the new language is properly integrated into the application:
71+
72+
- **Restart the Application**
73+
- Restart both the backend and frontend to ensure that all localization changes take effect.
74+
- **Select the New Language**
75+
- In your app, select the newly added language from the language selection drop-down menu and
76+
verify that user interface elements such as menus and labels are updated appropriately.
77+
- **Test Date Localizatio**
78+
- Open any date pickers and confirm that dates are displayed in the correct format for the selected language.
79+
80+
> Note: The newly added language and its XML content are stored in the database when the application runs.
81+
82+
## Conclusion
83+
By following these steps, you have successfully added support for a new language in your ASP.NET Zero MVC application. The localization process ensures that both backend and frontend components, including UI elements and date pickers, properly reflect the new language.
84+
85+
For more information, refer to the official documentation:
86+
- [ASP.NET Boilerplate Localization](https://aspnetboilerplate.com/Pages/Documents/Localization).
87+
- [ASP.NET Zero Language Management](https://aspnetboilerplate.com/Pages/Documents/Zero/Language-Management).

0 commit comments

Comments
 (0)