Why I build this localization library?

A user of the of my library AuthPermissions.AspNetCore (shortened to AuthP) wanted support for multiple languages (known as localization) added. I looked at the .NET localization service and here the main issues I had:

1. Makes your code harder to understand: The .NET's Localization replaces the message string to represent a message, which makes the code harder to understand, e.g. the error message “When using sharding the the hasOwnDb parameter must not be null.” would become a key something like “ShardingHasOwnDb”.
2. Makes it harder add localization to an existing app: Localization isn’t usually added at the start of a project (see MVP - Minimum Viable Product approach) so you most likely have code with messages built into your code at to start. .NET's Localization requires to remove the messages in your code and put them in the resource files - that's a lot of work.
3. Missing localized messages doesn't provide a good user experience: If you don't add a localizes message to the resource files, the the .NET localisation shows the key, e.g. “ShardingHasOwnDb”, which isn’t that useful to a user.
4. Makes a NuGet library hard to use / understand: Using a NuGet library that uses .NET's Localization would force you to set up the localization and it's resource files, which instantly makes the library hard to setup and understand.

It took me some time to design a library called Net.LocalizeMessagesAndErrors that solves issues above (and more). Plus, using the library on my AuthP library (which has hundreds of errors / messages) provides lots feedback on the best design for the library.

The full list of the benefits of the LocalizeWithDefault approach

Now that you have seen the two examples I can provide you with a longer list of LocalizeWithDefault's benefits.

• Easier to understand: Because the default message string is there to see in the code it’s easier to understand the code.
• Easier to localize: Typically, you will start building an application without localization. The LocalizeWithDefault methods makes it easier convert your code / messages to using localization.
• Easier to test: You can create a super-simple stub service to using your tests that just returns the default message without having to set up links to the localization resource files - see the Unit testing your localized code for more details.
• Better errors handling: If the StringLocalizer has a problem it can only return the localization key, which isn’t that useful, but LocalizeWithDefault service returns the default message, which the user could translate. Also, the LocalizeWithDefault service also logs any errors, including if a resource isn’t found, so it’s easier to find and fix problems.
• Better localize key handling: The Net.LocalizeMessagesAndError library uses extension methods to define the Localize Key (see Creating localize keys via extension methods for detailed information). The benefits of using methods over just providing a string are:
  • It provides an easier and clearer way to create a unique Localize Key as the extension methods can automatically provide the class and method part of the Localize Key.
  • The extension methods also have extra data on the class, method, and line number of where the localization method is called. This data is used in the logs when there is are errors and also provides a way to find and check the localized messages in your unit tests. See ??????????????????????????????????
• Can Ignore localization: If you don’t set up IStringLocalizer service, then the LocalizeWithDefault service will still run, but it always provides the default message. This is very useful for NuGet packages, as a developer can try out the library without having to set up .NET localization until they know they need localization.