Add new overloads to IStringLocalizerFactory to enable creating IStringLocalizer instances for a specific culture

[DamianEdwards]

Background and Motivation

We used to have an API on IStringLocalizer that would enable creating an instance for a specific culture, but it was removed (see #7756) due to reports of confusion by implementors. In doing so, we removed any non-static way of creating a localizer for a specific culture, which is necessary in scenarios where the current culture isn't implicitly set by the execution context, e.g. sending emails from a background worker. We've received feedback that this scenario is quite common and the lack of a first-class way to get a culture-specific instance of IStringLocalizer without resorting to static manipulation is undesirable.

Proposed API

Propose we add two new overloads with default implementations (to ensure the interface change isn't breaking) that allow creating IStringLocalizer instances for a specific culture:

public interface IStringLocalizerFactory
{
+    public IStringLocalizer Create(Type resourceSource, CultureInfo culture)
+    {
+        try
+        {
+            var originalCulture = CultureInfo.CurrentUICulture;
+            CultureInfo.CurrentUICulture = culture;
+            return Create(resourceSource);
+        }
+        finally
+        {
+            CultureInfo.CurentUICulture = originalCulture;
+        }
+    }
+    public IStringLocalizer Create(string baseName, string location, CultureInfo culture)
+    {
+       try
+        {
+            var originalCulture = CultureInfo.CurrentUICulture;
+            CultureInfo.CurrentUICulture = culture;
+            return Create(baseName, location);
+        }
+        finally
+        {
+            CultureInfo.CurentUICulture = originalCulture;
+        }
+    }
}

The implementation class ResourceManagerStringLocalizerFactory would be updated to implement these new methods to create instances of ResourceManagerStringLocalizer using the specified culture.

Usage Examples

public class EmailSender(IStringLocalizerFactory stringLocalizerFactory, CustomerDbContext db, IEmailSender emailSender)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        var since = DateTime.UtcNow - TimeSpan.FromDays(7);
        var customersToVerify = await db.Customers
            .Where(e => e.VerifiedOn == null && e.LastVerificationEmailSentOn >= since).Select(c => new { c.Id, c.FirstName, c.UICulture })
            .ToListAsync(cancellationToken);
        var templateName = "VerifyUser";
        var subject = "Please verify your email address";
        foreach (var customer in customersToVerify )
        {
            object[] parameters = [customer.FirstName];
            await emailSender.SendAsync(templateName, customer.Culture, subject, parameters, cancellationToken);
            await db.Customers.Where(c => c.Id == customer.Id)
                .ExecuteUpdateAsync(setters => setters.SetProperty(c => c.LastVerificationEmailSentOn = DateTime.UtcNow));
        }
    }
}

Alternative Designs

• A new interface like ICultureAwareStringLocalizerFactory that these methods are defined on but with no default implementation and that implementations have to add the culture-aware overloads for. Then consuming code would need to be updated to type-check for the new interface and if implemented, call the new methods on it, or the code could first attempt to resolve the new interface from DI, and if none is registered, fallback to the original interface and manually set the current culture before creating a localizer instance.
• Have the default implementations of the new overloads throw NotImplementedException rather than applying the current suggested workaround.

Risks

The default implementation setting static properties on CultureInfo could be problematic if not done correctly resulting in "leaking" culture specifics onto the current thread, but this is the approach we currently recommend to customers anyway.

[DamianEdwards]

FYI @halter73 @BrennanConroy @captainsafia for thoughts on proposed implementation here. Would be good to move this to api-ready-for-review/api-approved so we can accept a PR for it.

[martincostello]

Just because I stumbled across this just now while digging through some old code, and I found the solution I had to do to plug this gap for a headless serverless function that needed to read some text out of resx files to generate some content:

namespace MyApp.Resources;

public sealed class CultureSwitcher : IDisposable
{
    private readonly CultureInfo _originalCulture;

    public CultureSwitcher(string name)
    {
        var culture = CultureInfo.GetCultureInfo(name);
        _originalCulture = CultureInfo.CurrentCulture;
        CultureInfo.CurrentCulture = culture;
        CultureInfo.CurrentUICulture = culture;
    }

    public static IDisposable WithCulture(string name)
        => new CultureSwitcher(name);

    public void Dispose()
    {
        CultureInfo.CurrentCulture = _originalCulture;
        CultureInfo.CurrentUICulture = _originalCulture;
    }
}

Usage:

// Change the current culture so appropriate localized strings are used
using (CultureSwitcher.WithCulture(order.Language))
{
    return GenerateNotification(order); // Do stuff using resources
}

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[amcasey]

[API Review]

• Current mitigation/recommendation is to set the CurrentUICulture globally, use the localizer factory, and reset the CurrentUICulture
• Will the default implementations interact badly with caching
• The original implementation (since removed) was on the localizer, not the factory
• Need #ifdef for pre-core builds
• Should the default implementation update CurrentCulture in addition to CurrentUICulture?
  • Probably
• ResourceManagerStringLocalizerFactory is public and will also need updates
• The default implementation, as written in the description, doesn't seem like it will work
  • It should just throw
• Should IStringLocalizer expose a locale property?
  • We could use a separate interface, which would also work better with netstandard
• Note: location is about where to locate assets and is unrelated to geographic location
• We should make sure this works for the Orchard implementation
  • https://github.com/OrchardCMS/OrchardCore/blob/main/src/OrchardCore/OrchardCore.Localization.Core/PortableObject/PortableObjectStringLocalizerFactory.cs
  • https://github.com/OrchardCMS/OrchardCore/blob/main/src/OrchardCore/OrchardCore.Localization.Core/PortableObject/PortableObjectStringLocalizer.cs
• Is the factory the right place for this? It seems to allow late-binding, suggesting that passing the culture to the factory forces the decision to be made too early
  • Adding overloads to IStringLocalizer might work better for implementation
• Existing DI registration: https://source.dot.net/#Microsoft.Extensions.Localization/LocalizationServiceCollectionExtensions.cs,58
• Adding an indexer overload (to IStringLocalizer) would be awkward
• Will IHtmlLocalizer need to be updated as well?
  • Yes
• What about IViewLocalizer?
• We'll have a sensible default implementation in non-netstandard and ifdef them out in netstandard

[amcasey]

We should ensure that the doc comments for the members not taking a culture explain where they get the culture from.

[hishamco]

We already use a culture switcher in Orchard Core, and also I did this frequently in many projects. @DamianEdwards the proposal requires us to inject IStringLocalizerFactory. We might need something simple such as ResourceManagerWithCultureStringLocalizer if you recall