Improve usability of IHtmlLocalizer & associated API:

- IHtmlLocalizer no longer derives from IStringLocalizer
- IHtmlLocalizer indexer now returns LocalizedHtmlString
- IHtmlLocalizer has GetString methods now that act the same as IStringLocalizer.GetString
- Made LocalizedHtmlString a struct to match LocalizedString
- Updated samples in response to aspnet/Localization#167
- Rename "ancestor" to "parent" for loc API
- Fixes some doc comments
- Fixed tests
- #3716

Author: DamianEdwards

samples/LocalizationSample.Web/Resources/LocalizationSample.Web.Controllers.HomeController.fr.resx renamed to samples/LocalizationSample.Web/Resources/Controllers.HomeController.fr.resx

@@ -4,4 +4,4 @@
 }
 @LocString["Hello there!!"]
 @ViewBag.Message
-@LocString.Html("Hi", "John", @date , @date.DayOfWeek)
+@LocString.GetHtml("Hi", "John", @date , @date.DayOfWeek)

samples/LocalizationSample.Web/Resources/LocalizationSample.Web.Models.Product.fr.resx renamed to samples/LocalizationSample.Web/Resources/Models.Product.fr.resx

@@ -9,12 +9,12 @@
 namespace Microsoft.AspNet.Mvc.Localization
 {
     /// <summary>
-    /// An <see cref="IHtmlLocalizer"/> that uses the <see cref="IStringLocalizer"/> to provide localized HTML content.
-    /// This service just encodes the arguments but not the resource string.
+    /// An <see cref="IHtmlLocalizer"/> that uses the provided <see cref="IStringLocalizer"/> to do HTML-aware
+    /// localization of content.
     /// </summary>
     public class HtmlLocalizer : IHtmlLocalizer
     {
-        private IStringLocalizer _localizer;
+        private readonly IStringLocalizer _localizer;
 
         /// <summary>
         /// Creates a new <see cref="HtmlLocalizer"/>.
@@ -31,109 +31,68 @@ public HtmlLocalizer(IStringLocalizer localizer)
         }
 
         /// <inheritdoc />
-        public virtual LocalizedString this[string key]
+        public virtual LocalizedHtmlString this[string name]
         {
             get
             {
-                if (key == null)
+                if (name == null)
                 {
-                    throw new ArgumentNullException(nameof(key));
+                    throw new ArgumentNullException(nameof(name));
                 }
 
-                return _localizer[key];
+                return ToHtmlString(_localizer[name]);
             }
         }
 
         /// <inheritdoc />
-        public virtual LocalizedString this[string key, params object[] arguments]
+        public virtual LocalizedHtmlString this[string name, params object[] arguments]
         {
             get
             {
-                if (key == null)
+                if (name == null)
                 {
-                    throw new ArgumentNullException(nameof(key));
+                    throw new ArgumentNullException(nameof(name));
                 }
 
-                return _localizer[key, arguments];
+                return ToHtmlString(_localizer[name], arguments);
             }
         }
 
-        /// <summary>
-        /// Creates a new <see cref="IHtmlLocalizer"/> for a specific <see cref="CultureInfo"/>.
-        /// </summary>
-        /// <param name="culture">The <see cref="CultureInfo"/> to use.</param>
-        /// <returns>A culture-specific <see cref="IHtmlLocalizer"/>.</returns>
-        public virtual IHtmlLocalizer WithCulture(CultureInfo culture)
-        {
-            if (culture == null)
-            {
-                throw new ArgumentNullException(nameof(culture));
-            }
-
-            return new HtmlLocalizer(_localizer.WithCulture(culture));
-        }
-
-        /// <summary>
-        /// Creates a new <see cref="IStringLocalizer"/> for a specific <see cref="CultureInfo"/>.
-        /// </summary>
-        /// <param name="culture">The <see cref="CultureInfo"/> to use.</param>
-        /// <returns>A culture-specific <see cref="IStringLocalizer"/>.</returns>
-        IStringLocalizer IStringLocalizer.WithCulture(CultureInfo culture)
-        {
-            if (culture == null)
-            {
-                throw new ArgumentNullException(nameof(culture));
-            }
-
-            return new HtmlLocalizer(_localizer.WithCulture(culture));
-        }
-
         /// <inheritdoc />
-        public virtual LocalizedString GetString(string key)
+        public virtual LocalizedString GetString(string name)
         {
-            if (key == null)
+            if (name == null)
             {
-                throw new ArgumentNullException(nameof(key));
+                throw new ArgumentNullException(nameof(name));
             }
 
-            return _localizer.GetString(key);
+            return _localizer[name];
         }
 
         /// <inheritdoc />
-        public virtual LocalizedString GetString(string key, params object[] arguments)
+        public virtual LocalizedString GetString(string name, params object[] arguments)
         {
-            if (key == null)
+            if (name == null)
             {
-                throw new ArgumentNullException(nameof(key));
+                throw new ArgumentNullException(nameof(name));
             }
 
-            return _localizer.GetString(key, arguments);
+            return _localizer[name, arguments];
         }
 
         /// <inheritdoc />
-        public virtual IEnumerable<LocalizedString> GetAllStrings(bool includeAncestorCultures) =>
-            _localizer.GetAllStrings(includeAncestorCultures);
+        public virtual IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures) =>
+            _localizer.GetAllStrings(includeParentCultures);
 
         /// <inheritdoc />
-        public virtual LocalizedHtmlString Html(string key)
-        {
-            if (key == null)
-            {
-                throw new ArgumentNullException(nameof(key));
-            }
-
-            return ToHtmlString(_localizer.GetString(key));
-        }
-
-        /// <inheritdoc />
-        public virtual LocalizedHtmlString Html(string key, params object[] arguments)
+        public virtual IHtmlLocalizer WithCulture(CultureInfo culture)
         {
-            if (key == null)
+            if (culture == null)
             {
-                throw new ArgumentNullException(nameof(key));
+                throw new ArgumentNullException(nameof(culture));
             }
 
-            return ToHtmlString(_localizer.GetString(key), arguments);
+            return new HtmlLocalizer(_localizer.WithCulture(culture));
         }
 
         /// <summary>

samples/LocalizationSample.Web/Resources/LocalizationSample.Web.Models.User.fr.resx renamed to samples/LocalizationSample.Web/Resources/Models.User.fr.resx

@@ -0,0 +1,71 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.Localization;
+
+namespace Microsoft.AspNet.Mvc.Localization
+{
+    /// <summary>
+    /// Extension methods for <see cref="IHtmlLocalizer"/>.
+    /// </summary>
+    public static class HtmlLocalizerExtensions
+    {
+        /// <summary>
+        /// Gets the <see cref="LocalizedHtmlString"/> resource for a specific name.
+        /// </summary>
+        /// <param name="key">The key to use.</param>
+        /// <returns>The <see cref="LocalizedHtmlString"/> resource.</returns>
+        public static LocalizedHtmlString GetHtml(this IHtmlLocalizer htmlLocalizer, string name)
+        {
+            if (htmlLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(htmlLocalizer));
+            }
+
+            if (name == null)
+            {
+                throw new ArgumentNullException(nameof(name));
+            }
+
+            return htmlLocalizer[name];
+        }
+
+        /// <summary>
+        /// Gets the <see cref="LocalizedHtmlString"/> resource for a specific name.
+        /// </summary>
+        /// <param name="key">The key to use.</param>
+        /// <param name="arguments">The values to format the string with.</param>
+        /// <returns>The <see cref="LocalizedHtmlString"/> resource.</returns>
+        public static LocalizedHtmlString GetHtml(this IHtmlLocalizer htmlLocalizer, string name, params object[] arguments)
+        {
+            if (htmlLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(htmlLocalizer));
+            }
+
+            if (name == null)
+            {
+                throw new ArgumentNullException(nameof(name));
+            }
+
+            return htmlLocalizer[name, arguments];
+        }
+
+        /// <summary>
+        /// Gets all string resources including those for parent cultures.
+        /// </summary>
+        /// <param name="htmlLocalizer">The <see cref="IHtmlLocalizer"/>.</param>
+        /// <returns>The string resources.</returns>
+        public static IEnumerable<LocalizedString> GetAllStrings(this IHtmlLocalizer htmlLocalizer)
+        {
+            if (htmlLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(htmlLocalizer));
+            }
+
+            return htmlLocalizer.GetAllStrings(includeParentCultures: true);
+        }
+    }
+}

samples/LocalizationSample.Web/Views/Home/Locpage.cshtml

@@ -7,14 +7,15 @@
 namespace Microsoft.AspNet.Mvc.Localization
 {
     /// <summary>
-    /// An <see cref="IHtmlLocalizerFactory"/> that creates instances of <see cref="HtmlLocalizer"/>.
+    /// An <see cref="IHtmlLocalizerFactory"/> that creates instances of <see cref="HtmlLocalizer"/> using the
+    /// registered <see cref="IStringLocalizerFactory"/>.
     /// </summary>
     public class HtmlLocalizerFactory : IHtmlLocalizerFactory
     {
         private readonly IStringLocalizerFactory _factory;
 
         /// <summary>
-        /// Creates a new <see cref="HtmlLocalizer"/>.
+        /// Creates a new <see cref="HtmlLocalizerFactory"/>.
         /// </summary>
         /// <param name="localizerFactory">The <see cref="IStringLocalizerFactory"/>.</param>
         public HtmlLocalizerFactory(IStringLocalizerFactory localizerFactory)
@@ -28,10 +29,9 @@ public HtmlLocalizerFactory(IStringLocalizerFactory localizerFactory)
         }
 
         /// <summary>
-        /// Creates an <see cref="HtmlLocalizer"/> using the <see cref="System.Reflection.Assembly"/> and
-        /// <see cref="Type.FullName"/> of the specified <see cref="Type"/>.
+        /// Creates an <see cref="HtmlLocalizer"/> using the specified <see cref="Type"/>.
         /// </summary>
-        /// <param name="resourceSource">The <see cref="Type"/>.</param>
+        /// <param name="resourceSource">The <see cref="Type"/> to load resources for.</param>
         /// <returns>The <see cref="HtmlLocalizer"/>.</returns>
         public virtual IHtmlLocalizer Create(Type resourceSource)
         {
@@ -44,7 +44,7 @@ public virtual IHtmlLocalizer Create(Type resourceSource)
         }
 
         /// <summary>
-        /// Creates an <see cref="HtmlLocalizer"/>.
+        /// Creates an <see cref="HtmlLocalizer"/> using the specified base name and location.
         /// </summary>
         /// <param name="baseName">The base name of the resource to load strings from.</param>
         /// <param name="location">The location to load resources from.</param>