Home

Welcome to the Net.LocalizeMessagesAndErrors documentation

This library provides extra code to make it easier to support in different languages in your .NET application (known as localization in .NET). The code in this library provide wraps the .NET's localization services with a nicer front-end that makes the localization parts easier to code and understand.

See the sidebar on the right for more detailed documentation.

The key feature of this library is that it allows you to provide the text in your default language. This makes it easier to understand the code because the text is there. In the example, taken from a ASP.NET Core View, the "Set string" is easy to see, which makes easier to understand the code.

<button type="submit" class="btn btn-success">
    @(SimpleLocalizer.LocalizeString("Set string", this))
</button>

All the services in this library work the same:

• If the user's culture matches the culture of your strings (defined at registration), then the default string is returned, e.g send back "Set string"
• If the user's culture doesn't match the default string culture, then the .NET's localization service is called to lookup your alternative language version in the correct resource file.
  • If the lookup succeeded, then the string would be returned, e.g. if the user's culture is "fi" (generic French), then it would return the string set, which in my case is "Définir la chaîne".
  • If the lookup fails, then it returns the default string (e.g. "set String") and logs a warning with full information where that message / key was triggered. This is better that .NET's localization, which would return the key which might not be very informative.

The three parts of this library are:

ISimpleLocalizer - good for simple / short messages

This is aimed at adding messages into ASP.NET Core Views / Pages. The code below comes from the CheckNull.cshtml View and has two localized strings in the form.

<form method="post">
    <div asp-validation-summary="All" class="text-danger"></div>
    <div class="form-group">

        <label for="month">
            @(SimpleLocalizer.LocalizeString("Provide a string (can be null)", this))
        </label>
        <input type="text" id="month" name="month">

        <div class="col-md-2">
            <button type="submit" class="btn btn-success">
                @(SimpleLocalizer.LocalizeString("Set string", this))
            </button>
        </div>
    </div>
</form>

ISimpleLocalizer is simple to use, but has a few limitations such as where the extra languages are stored.

NOTE: The SimpleLocalizer relies on the LocalizeWithDefault<TResource> service, which is described next.

LocalizeWithDefault<TResource> service - good in your backend code

This service provides a ways to define the Name (referred to as localize key) of the resource file lookup using the name of the class and/or method where your default message is. The code below is taken from the DefaultLocalizerController in this repo.

public IActionResult StringMessage()
{
    return View((object)
       _localizer.LocalizeStringMessage(          //method that takes a string
        "ExampleMessage".MethodLocalizeKey(this), //localize key is "StringMessage_ExampleMessage"
        "Hello from me!"                          //The message, in the default culture
    ));
}

This makes the localize keys easier to understand / find, which is important once to have lots of message to localize. This approach also allows you cut / paste code from one method / class and the localize key will automatically updated.

StatusGenericLocalizer - good for methods that can return errors

This is version of my library called called GenericServices.StatusGeneric that provides a small, but powerful status handler. The StatusGenericLocalizer is provides the same features, but also provide localization of the errors/success messages. See

public IStatusGeneric StatusGenericWithResult(int year)
{
    var status = new StatusGenericLocalizer<TResource>(_defaultLocalizer);

    //add error and return immediately
    if (year < 0)
        return status.AddErrorString("NumberNegative".ClassMethodLocalizeKey(this, false),
            "The property should not be negative.", nameof(year).CamelToPascal());

    return status;
}

I needed this to localize my AuthPermissions.AspNetCore but you might find it useful in your application.