-
Notifications
You must be signed in to change notification settings - Fork 10.5k
Description
Background and Motivation
This API addresses the need to persist culture information from server-side rendering to WebAssembly components during hydration. Currently, when Blazor WebAssembly components are prerendered on the server with a specific culture, that culture information is lost when the components become interactive on the client side. This creates inconsistency in localization behavior between server-side rendering and client-side interactivity.
The proposed solution enables automatic persistence of CultureInfo.CurrentCulture
and CultureInfo.CurrentUICulture
from the server to the WebAssembly client, ensuring consistent localization throughout the component lifecycle.
Proposed API
namespace Microsoft.Extensions.DependencyInjection
{
public static class WebAssemblyRazorComponentsBuilderExtensions
{
public static IRazorComponentsBuilder AddInteractiveWebAssemblyComponents(this IRazorComponentsBuilder builder);
+ public static IRazorComponentsBuilder AddInteractiveWebAssemblyComponents(this IRazorComponentsBuilder builder, bool persistCultureFromServer);
}
}
Usage Examples
// Enable culture persistence (default behavior)
builder.Services.AddRazorComponents()
.AddInteractiveWebAssemblyComponents();
// Explicitly enable culture persistence
builder.Services.AddRazorComponents()
.AddInteractiveWebAssemblyComponents(persistCultureFromServer: true);
// Disable culture persistence
builder.Services.AddRazorComponents()
.AddInteractiveWebAssemblyComponents(persistCultureFromServer: false);
When enabled, the server culture will be automatically captured during prerendering and restored on the WebAssembly client:
@* Server sets culture to fr-FR during prerendering *@
@page "/my-component"
@using System.Globalization
<p>Culture: @CultureInfo.CurrentCulture.Name</p>
<p>UI Culture: @CultureInfo.CurrentUICulture.Name</p>
@* After WebAssembly hydration, culture remains fr-FR when persistence is enabled *@
Alternative Designs
Several alternative approaches were considered:
-
Manual culture persistence: Requiring developers to manually persist and restore culture using
PersistentComponentState
. This approach would provide more control but increase boilerplate code. -
Always-on culture persistence: Making culture persistence mandatory without an opt-out option. This was rejected to maintain backward compatibility.
-
Separate API for culture configuration: Creating a dedicated method like
ConfigureCulturePersistence()
. This was deemed unnecessary for a single boolean flag.
The proposed design was chosen because it leverages the existing persistent component state infrastructure and provides a simple opt-in/opt-out mechanism while maintaining backward compatibility through method overloading.
Risks
- Breaking Change in Default Behavior: The parameterless
AddInteractiveWebAssemblyComponents()
now defaults to enabling culture persistence (persistCultureFromServer: true
). This changes existing behavior and could affect applications that rely on WebAssembly components using default culture instead of server culture.