Supporting multiple languages

The 4.1.0 version (or higher) AuthP library has a built-in localization system using my Net.LocalizeMessagesAndErrors library. By default it is turned off so you can use the AuthP library without having to set up the .NET localization service and resource files. To turn on localization in your code that uses the AuthP library you need to:

1. Register the .NET localization service in your ASP.NET Core.
2. Register the AuthP localization service in your Program class.
3. Create resource file(s) for the AuthP messages for other languages.
4. Add localization to your own code.

1. Register the .NET localization service.

I have covered this in my Net.LocalizeMessagesAndErrors documentation which links to apps that have .NET localization set up, so please use that to set up the .NET localization service.

You can also look at the Example1's Program class, which has been setup such that the user can select what culture they want.

2. Register the AuthP localization service.

You add the SetupAuthPLocalization<TResource> extension method within the registering of the AuthP library. The code below, taken from the Program class in Example1, that sets up the AuthP localization of its backend code.

builder.Services.RegisterAuthPermissions<Example1Permissions>()
    .SetupAuthPLocalization<AuthPLocalizeResource>(supportedCultures)
    // other AuthP's registering left out 

The AuthPLocalizeResource class in the Example1 ASP.NET Core's project is there to define part of the resource file(s) name that will hold the AuthP messages in the extra languages you want to support (see next section about this). You can have a class with a different or location, but it must be in the ASP.NET Core's project.

The supportedCulture parameter should be set to an array of culture names your app supports, e.g new[] { "en", "fr" }. This list can usually come from your code to register the .NET localization service.

NOTE: See a more detailed list of the possible supportedCulture settings in the Startup code -> SetupAuthPLocalization section.

3. Create resource file(s) for the AuthP messages for other languages.

The AuthP library has >100 messages (mostly error messages) which you need changed into the non-English languages. For this you need a resource file for every language, other than English.

To help you to set up each resource file there is a file called AuthPermissions - list of localizable keys & messages - english.csv which contains the Name and Value of each AuthP possible messages, but the Value is in English. You have to translate the English Value to the language(s) you want to support.

This is a tedious job, but having the the complete set of Name / Value will make the process easier, and you can be sure you have covered all the messages.

NOTE: in the article about the Net.LocalizeMessagesAndErrors library I give a tip on how to build resource files by using Excel to input the Name / Value entries and then use code to create the resource file.

4. Add localization to your own code.

There are three steps you need to go though to localize the code in your application, as listed below:

• a. Setting up resource file(s) for your code / frontend.
• b. Localize your code / front-end.
• c. How to handle the messages from the AuthP services.

The following sub-sections with cover these parts:

4a. Setting up resource file(s) for your code / frontend.

In step 3 you added a resource file for the AuthP messages. Now you need to create resource file(s) for your code and front-end. The process is the same as step three, but the Names / Values are defined by you.

In the Example1 web app I added a class called AppLocalizeResource which defined the name of the resource file. I was using the Net.LocalizeMessagesAndErrors library so I only needed a French resource file, which had the name AppLocalizeResource.fr.resx.

4b. Localize your code / front-end.

In your own code you can localize your code in any way you want to - using the .NET localization services, or my Net.LocalizeMessagesAndErrors library, or both.

If you want to use .NET localization services then try the Microsoft docs. NOTE: There are links to other information at the end of this section one of my articles.

If you want to use Net.LocalizeMessagesAndErrors library, then look at its documentation. But be aware, in the AuthP library the default culture of the messages is "en" (generic English), so if English isn't the main culture, then you shouldn't use the Net.LocalizeMessagesAndErrors library.

I used the Net.LocalizeMessagesAndErrors's ISimpleLocalizer service, which is targetted at simple messages used in front-end code, in the Example1 web app - here is a link to the Create Role razor code where I used the ISimpleLocalizer service. NOTE: you have to manually register the ISimpleLocalizer - see this document for how you do that.

I didn't used the IDefaultLocalizer service (which is registered by AuthP) because the Example1 web app didn't have any backend code, but there is backend code you might use it. The IDefaultLocalizer has a more localize key settings

4c. How to handle the messages from the AuthP services.

Any AuthP service that can return errors returns a status, which contains a list of errors (empty if no errors) and a Message, which will contain a success message, if there are no errors. It also has a IsValid and HasErrors bool properties that are true and false respectively if there are no errors. See the IStatusGeneric interface for full information.

Version 4.1.0 has a localized the success and error messages returned, so you can show these to the user. In the Example1 web app I also added the NuGet called EfCore.GenericServices.AspNetCore which can copy the IStatusGeneric errors into the ASP.NET.Core's ModelState, which will display the error in the correct place - see the Create Role Page code on line 36.

Click this to see the English / French screenshot with the error shown next to the Role Name.