Merge source code from aspnet/Localization

\n\nCommit migrated from dotnet/extensions@9c7e86f

Author: Nate McMaster

src/Localization/Abstractions/src/IStringLocalizer.cs

@@ -0,0 +1,45 @@
+// 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.Collections.Generic;
+using System.Globalization;
+
+namespace Microsoft.Extensions.Localization
+{
+    /// <summary>
+    /// Represents a service that provides localized strings.
+    /// </summary>
+    public interface IStringLocalizer
+    {
+        /// <summary>
+        /// Gets the string resource with the given name.
+        /// </summary>
+        /// <param name="name">The name of the string resource.</param>
+        /// <returns>The string resource as a <see cref="LocalizedString"/>.</returns>
+        LocalizedString this[string name] { get; }
+
+        /// <summary>
+        /// Gets the string resource with the given name and formatted with the supplied arguments.
+        /// </summary>
+        /// <param name="name">The name of the string resource.</param>
+        /// <param name="arguments">The values to format the string with.</param>
+        /// <returns>The formatted string resource as a <see cref="LocalizedString"/>.</returns>
+        LocalizedString this[string name, params object[] arguments] { get; }
+
+        /// <summary>
+        /// Gets all string resources.
+        /// </summary>
+        /// <param name="includeParentCultures">
+        /// A <see cref="System.Boolean"/> indicating whether to include strings from parent cultures.
+        /// </param>
+        /// <returns>The strings.</returns>
+        IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures);
+
+        /// <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 WithCulture(CultureInfo culture);
+    }
+}

src/Localization/Abstractions/src/IStringLocalizerFactory.cs

@@ -0,0 +1,29 @@
+// 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;
+
+namespace Microsoft.Extensions.Localization
+{
+    /// <summary>
+    /// Represents a factory that creates <see cref="IStringLocalizer"/> instances.
+    /// </summary>
+    public interface IStringLocalizerFactory
+    {
+        /// <summary>
+        /// Creates an <see cref="IStringLocalizer"/> using the <see cref="System.Reflection.Assembly"/> and
+        /// <see cref="Type.FullName"/> of the specified <see cref="Type"/>.
+        /// </summary>
+        /// <param name="resourceSource">The <see cref="Type"/>.</param>
+        /// <returns>The <see cref="IStringLocalizer"/>.</returns>
+        IStringLocalizer Create(Type resourceSource);
+
+        /// <summary>
+        /// Creates an <see cref="IStringLocalizer"/>.
+        /// </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>
+        /// <returns>The <see cref="IStringLocalizer"/>.</returns>
+        IStringLocalizer Create(string baseName, string location);
+    }
+}

src/Localization/Abstractions/src/IStringLocalizerOfT.cs

@@ -0,0 +1,14 @@
+// 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. 
+
+namespace Microsoft.Extensions.Localization
+{
+    /// <summary>
+    /// Represents an <see cref="IStringLocalizer"/> that provides strings for <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The <see cref="System.Type"/> to provide strings for.</typeparam>
+    public interface IStringLocalizer<T> : IStringLocalizer
+    {
+
+    }
+}

src/Localization/Abstractions/src/LocalizedString.cs

@@ -0,0 +1,90 @@
+// 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;
+
+namespace Microsoft.Extensions.Localization
+{
+    /// <summary>
+    /// A locale specific string.
+    /// </summary>
+    public class LocalizedString
+    {
+        /// <summary>
+        /// Creates a new <see cref="LocalizedString"/>.
+        /// </summary>
+        /// <param name="name">The name of the string in the resource it was loaded from.</param>
+        /// <param name="value">The actual string.</param>
+        public LocalizedString(string name, string value)
+            : this(name, value, resourceNotFound: false)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="LocalizedString"/>.
+        /// </summary>
+        /// <param name="name">The name of the string in the resource it was loaded from.</param>
+        /// <param name="value">The actual string.</param>
+        /// <param name="resourceNotFound">Whether the string was not found in a resource. Set this to <c>true</c> to indicate an alternate string value was used.</param>
+        public LocalizedString(string name, string value, bool resourceNotFound)
+            : this(name, value, resourceNotFound, searchedLocation: null)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="LocalizedString"/>.
+        /// </summary>
+        /// <param name="name">The name of the string in the resource it was loaded from.</param>
+        /// <param name="value">The actual string.</param>
+        /// <param name="resourceNotFound">Whether the string was not found in a resource. Set this to <c>true</c> to indicate an alternate string value was used.</param>
+        /// <param name="searchedLocation">The location which was searched for a localization value.</param>
+        public LocalizedString(string name, string value, bool resourceNotFound, string searchedLocation)
+        {
+            if (name == null)
+            {
+                throw new ArgumentNullException(nameof(name));
+            }
+
+            if (value == null)
+            {
+                throw new ArgumentNullException(nameof(value));
+            }
+
+            Name = name;
+            Value = value;
+            ResourceNotFound = resourceNotFound;
+            SearchedLocation = searchedLocation;
+        }
+
+        public static implicit operator string(LocalizedString localizedString)
+        {
+            return localizedString?.Value;
+        }
+
+        /// <summary>
+        /// The name of the string in the resource it was loaded from.
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// The actual string.
+        /// </summary>
+        public string Value { get; }
+
+        /// <summary>
+        /// Whether the string was not found in a resource. If <c>true</c>, an alternate string value was used.
+        /// </summary>
+        public bool ResourceNotFound { get; }
+
+        /// <summary>
+        /// The location which was searched for a localization value.
+        /// </summary>
+        public string SearchedLocation { get; }
+
+        /// <summary>
+        /// Returns the actual string.
+        /// </summary>
+        /// <returns>The actual string.</returns>
+        public override string ToString() => Value;
+    }
+}

src/Localization/Abstractions/src/Microsoft.Extensions.Localization.Abstractions.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <Product>Microsoft .NET Extensions</Product>
+    <Description>Abstractions of application localization services.
+Commonly used types:
+Microsoft.Extensions.Localization.IStringLocalizer
+Microsoft.Extensions.Localization.IStringLocalizer&lt;T&gt;</Description>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <PackageTags>localization</PackageTags>
+  </PropertyGroup>
+
+</Project>

src/Localization/Abstractions/src/StringLocalizerExtensions.cs

@@ -0,0 +1,74 @@
+// 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;
+
+namespace Microsoft.Extensions.Localization
+{
+    public static class StringLocalizerExtensions
+    {
+        /// <summary>
+        /// Gets the string resource with the given name.
+        /// </summary>
+        /// <param name="stringLocalizer">The <see cref="IStringLocalizer"/>.</param>
+        /// <param name="name">The name of the string resource.</param>
+        /// <returns>The string resource as a <see cref="LocalizedString"/>.</returns>
+        public static LocalizedString GetString(
+            this IStringLocalizer stringLocalizer,
+            string name)
+        {
+            if (stringLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(stringLocalizer));
+            }
+
+            if (name == null)
+            {
+                throw new ArgumentNullException(nameof(name));
+            }
+
+            return stringLocalizer[name];
+        }
+
+        /// <summary>
+        /// Gets the string resource with the given name and formatted with the supplied arguments.
+        /// </summary>
+        /// <param name="stringLocalizer">The <see cref="IStringLocalizer"/>.</param>
+        /// <param name="name">The name of the string resource.</param>
+        /// <param name="arguments">The values to format the string with.</param>
+        /// <returns>The formatted string resource as a <see cref="LocalizedString"/>.</returns>
+        public static LocalizedString GetString(
+            this IStringLocalizer stringLocalizer,
+            string name,
+            params object[] arguments)
+        {
+            if (stringLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(stringLocalizer));
+            }
+
+            if (name == null)
+            {
+                throw new ArgumentNullException(nameof(name));
+            }
+
+            return stringLocalizer[name, arguments];
+        }
+
+        /// <summary>
+        /// Gets all string resources including those for parent cultures.
+        /// </summary>
+        /// <param name="stringLocalizer">The <see cref="IStringLocalizer"/>.</param>
+        /// <returns>The string resources.</returns>
+        public static IEnumerable<LocalizedString> GetAllStrings(this IStringLocalizer stringLocalizer)
+        {
+            if (stringLocalizer == null)
+            {
+                throw new ArgumentNullException(nameof(stringLocalizer));
+            }
+
+            return stringLocalizer.GetAllStrings(includeParentCultures: true);
+        }
+    }
+}

src/Localization/Abstractions/src/StringLocalizerOfT.cs

@@ -0,0 +1,67 @@
+// 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 System.Globalization;
+
+namespace Microsoft.Extensions.Localization
+{
+    /// <summary>
+    /// Provides strings for <typeparamref name="TResourceSource"/>.
+    /// </summary>
+    /// <typeparam name="TResourceSource">The <see cref="Type"/> to provide strings for.</typeparam>
+    public class StringLocalizer<TResourceSource> : IStringLocalizer<TResourceSource>
+    {
+        private IStringLocalizer _localizer;
+
+        /// <summary>
+        /// Creates a new <see cref="StringLocalizer{TResourceSource}"/>.
+        /// </summary>
+        /// <param name="factory">The <see cref="IStringLocalizerFactory"/> to use.</param>
+        public StringLocalizer(IStringLocalizerFactory factory)
+        {
+            if (factory == null)
+            {
+                throw new ArgumentNullException(nameof(factory));
+            }
+
+            _localizer = factory.Create(typeof(TResourceSource));
+        }
+
+        /// <inheritdoc />
+        public virtual IStringLocalizer WithCulture(CultureInfo culture) => _localizer.WithCulture(culture);
+
+        /// <inheritdoc />
+        public virtual LocalizedString this[string name]
+        {
+            get
+            {
+                if (name == null)
+                {
+                    throw new ArgumentNullException(nameof(name));
+                }
+
+                return _localizer[name];
+            }
+        }
+
+        /// <inheritdoc />
+        public virtual LocalizedString this[string name, params object[] arguments]
+        {
+            get
+            {
+                if (name == null)
+                {
+                    throw new ArgumentNullException(nameof(name));
+                }
+
+                return _localizer[name, arguments];
+            }
+        }
+
+        /// <inheritdoc />
+        public IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures) =>
+            _localizer.GetAllStrings(includeParentCultures);
+    }
+}