Use/Mention IHtmlLocalizer.GetString in Localization doc

[FranklinWhale]

Globalization and localization in ASP.NET Core provides the following information about IHtmlLocalizer and ViewLocalizer:

Use the IHtmlLocalizer<T> implementation for resources that contain HTML.

IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself.

ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. You can parameterize resource strings and IViewLocalizer will HTML encode the parameters, but not the resource string.

It also gives the note below twice:

Note: You generally want to only localize text and not HTML.

The effect of the above, in my view, is that although HTML may be put in resources and may be localized without being encoded using IHtmlLocalizer, generally speaking, only text should be included in resources. That would be fine if the HTML encoding behavior of IHtmlLocalizer is an opt-in. Unfortunately, since the injection of an IViewLocalizer is the easiest way for a MVC view or Razor page to get a localizer and IViewLocalizer extends IHtmlLocalizer, all localized strings from IViewLocalizer are not HTML encoded. This is confusing because other values on the same page, such that those from Model and IStringLocalizer<SharedResource>, are HTML encoded.

Adding to the confusion is that wrapping an IViewLocalizer value with Html.Encode makes the situation worse as the value is then double encoded.

I initially thought it is a bug (See aspnet/Mvc#8225). After a more careful reading of the document and ASP.NET Core API Reference, I find that localized values that are retrieved through the IHtmlLocalizer.GetString extension method instead of the index property are HTML encoded. The IHtmlLocalizer.GetString extension method is probably the easiest way to opt out of the HTML encoding behavior of IHtmlLocalizer and I think it should be mentioned in the document with examples.

Finally, since there is a similar extension method for IStringLocalizer and a GetHtml extension method, to make the HTML encoding behavior more consistent and easier to understand, perhaps in the examples all localized values that should be HTML encoded should be retrieved through the GetString extension method while those requiring the behavior of IHtmlLocalizer should be retrieved through the GetHtml extension method. The use of the index property should be discouraged.

[Rick-Anderson]

@ryanbrandenburg please review.

[FranklinWhale]

Edited the issue above to suggest replacing the index properties with either GetString or GetHtml

[hishamco]

I think I need to mention some of what you wrote in dotnet/aspnetcore#3289 to make the APIs consistent in IStringLocalizer, IViewLocalizer & IHtmlStringLocalizer

[hishamco]

FYI the issue that I referenced earlier is unfortunately closed 😞, @Rick-Anderson what's the action needed here?

[Rick-Anderson]

Thanks for contacting us.
We don’t have the resources to invest in this area, so we are closing the issue. Should your request generate enough 👍 responses, we’ll reconsider.